# Troubleshooting Guide - @erpsquad/common This guide covers common issues and solutions when using the @erpsquad/common library. ## 🎨 Styling Issues ### ⚠️ Components Have No Styling **Symptoms:** - Components render but look completely unstyled - Missing colors, spacing, or layout - Components appear as plain HTML elements **Cause:** The CSS file is not imported in your application. **Solution:** Add this import to your main application file (`main.tsx`, `App.tsx`, or `index.tsx`): ```tsx // ⚠️ This MUST be imported in your application entry point! import '@erpsquad/common/style.css'; ``` **Complete Example:** ```tsx // main.tsx or App.tsx import React from 'react'; import ReactDOM from 'react-dom/client'; // 👇 Import CSS first, before any components! import '@erpsquad/common/style.css'; import App from './App'; ReactDOM.createRoot(document.getElementById('root')!).render( ); ``` ### CSS Not Loading in Vite Projects **Problem:** CSS doesn't load even after importing `style.css`. **Solution:** 1. Ensure the import is at the top of your entry file 2. Clear Vite cache: `rm -rf node_modules/.vite` or `rimraf node_modules/.vite` 3. Restart dev server: `npm run dev` ### CSS Not Loading in Webpack Projects **Problem:** Webpack doesn't process the CSS import. **Solution:** Ensure your webpack config has CSS loaders: ```js // webpack.config.js module.exports = { module: { rules: [ { test: /\.css$/, use: ['style-loader', 'css-loader'] } ] } }; ``` Install loaders if missing: ```bash npm install --save-dev style-loader css-loader ``` ### CSS Not Loading in Next.js Projects **Problem:** Next.js doesn't allow CSS imports from `node_modules` by default. **Solution:** Import the CSS in `_app.tsx` or `_app.js`: ```tsx // pages/_app.tsx import '@erpsquad/common/style.css'; // ✅ Import here function MyApp({ Component, pageProps }) { return } export default MyApp; ``` Or for App Router (Next.js 13+), import in `app/layout.tsx`: ```tsx // app/layout.tsx import '@erpsquad/common/style.css'; // ✅ Import here export default function RootLayout({ children }) { return ( {children} ); } ``` ### Styles Conflicting with Existing CSS **Problem:** Library styles override your application styles or vice versa. **Solution:** 1. **Import order matters** - Import library CSS before your own: ```tsx import '@erpsquad/common/style.css'; // Library styles import './App.css'; // Your styles (will override library) ``` 2. **Use CSS specificity** - Make your styles more specific: ```css /* Instead of */ .button { color: red; } /* Use */ .my-app .button { color: red; } ``` 3. **Use CSS Modules** for your components to avoid conflicts ### Chart Components Have No Styling **Problem:** Chart components (BarChart, DonutChart, etc.) render but have no styling. **Solution:** Same as above - ensure you've imported the main CSS file: ```tsx import '@erpsquad/common/style.css'; ``` The chart styles are included in the bundled `style.css` file. Individual chart stylesheets are automatically bundled during the build process. --- ## 📦 Import Issues ### Cannot Resolve Module **Error:** ``` Cannot resolve '@erpsquad/common/components' ``` **Solution:** 1. Install required peer dependencies: ```bash npm install @mui/material @emotion/react @emotion/styled ``` 2. Use correct import paths: ```tsx // ✅ Correct import { Button } from '@erpsquad/common/components'; // ❌ Incorrect import { Button } from '@erpsquad/common'; ``` ### Module Not Found During Build **Error:** ``` Module not found: Can't resolve '@erpsquad/common/components' ``` **Solution:** 1. Clear node_modules and reinstall: ```bash rm -rf node_modules package-lock.json npm install ``` 2. For Vite projects, add to `vite.config.ts`: ```ts export default defineConfig({ optimizeDeps: { include: ['@erpsquad/common'] } }); ``` ### TypeScript Cannot Find Types **Error:** ``` Cannot find module '@erpsquad/common' or its corresponding type declarations ``` **Solution:** 1. Ensure the package is installed: `npm install @erpsquad/common` 2. Restart TypeScript server in your IDE 3. Check `tsconfig.json` has proper module resolution: ```json { "compilerOptions": { "moduleResolution": "node", "esModuleInterop": true } } ``` --- ## 🔧 Build Issues ### Vite Build Fails **Error:** ``` Build failed with error: ... ``` **Solutions:** 1. Add to `vite.config.ts`: ```ts export default defineConfig({ build: { commonjsOptions: { include: [/@erpsquad\/common/, /node_modules/] } }, optimizeDeps: { include: ['@erpsquad/common'] } }); ``` 2. Clear Vite cache: ```bash rm -rf node_modules/.vite dist npm run build ``` ### Webpack Bundle Size Too Large **Problem:** Bundle size is unexpectedly large when using the library. **Solution:** 1. Use path-specific imports to enable tree-shaking: ```tsx // ✅ Good - only bundles Button import { Button } from '@erpsquad/common/components'; // ❌ Bad - might bundle more than needed import * as Common from '@erpsquad/common'; ``` 2. Ensure your webpack config has tree-shaking enabled: ```js module.exports = { mode: 'production', optimization: { usedExports: true, sideEffects: true } }; ``` --- ## ⚛️ React Issues ### Multiple React Instances **Error:** ``` Invalid hook call. Hooks can only be called inside of the body of a function component. ``` **Cause:** Multiple versions of React in your project. **Solution:** 1. Check for duplicate React: ```bash npm ls react ``` 2. Ensure single React version in `package.json`: ```json { "dependencies": { "react": "^18.2.0" }, "resolutions": { "react": "^18.2.0" } } ``` 3. For pnpm, add to `.npmrc`: ``` shamefully-hoist=true ``` ### Context Providers Not Working **Problem:** `useAuth`, `useLanguage`, etc. return `undefined` or throw errors. **Solution:** Wrap your app with `ERPUIProvider`: ```tsx import '@erpsquad/common/style.css'; import { ERPUIProvider } from '@erpsquad/common/contexts'; function App() { return ( {/* Your components here */} ); } ``` --- ## 🌐 i18n Issues ### Translations Not Loading **Problem:** Components display translation keys instead of actual text. **Solution:** 1. Install i18n dependencies: ```bash npm install react-i18next i18next i18next-http-backend ``` 2. Configure i18n in your app: ```tsx import { initI18n } from '@erpsquad/common/utils'; initI18n(); ``` --- ## 🔴 Redux Issues ### Redux Actions Not Working **Problem:** Redux slices from the library don't work. **Solution:** 1. Install Redux dependencies: ```bash npm install @reduxjs/toolkit react-redux ``` 2. Include library slices in your store: ```tsx import { configureStore } from '@reduxjs/toolkit'; import { createStore } from '@erpsquad/common/redux'; const store = createStore({ // Your reducers }); ``` --- ## 🆘 Still Having Issues? If none of these solutions work: 1. **Check the examples**: Review working examples in the `/examples` folder 2. **Search issues**: [GitHub Issues](https://github.com/erpforce/common/issues) 3. **Create an issue**: Include: - Error message - Code snippet - Package versions (`npm list @erpsquad/common react`) - Build tool (Vite/Webpack/Next.js) 4. **Check version compatibility**: Ensure you're using compatible versions of peer dependencies ### Diagnostic Commands Run these to gather information for bug reports: ```bash # Check package version npm list @erpsquad/common # Check peer dependencies npm list react react-dom @mui/material # Check for duplicate packages npm ls react # Verify package installation npm info @erpsquad/common # Clear all caches and reinstall rm -rf node_modules package-lock.json dist .next .vite npm install ```