# 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(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);
```

### 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 <Component {...pageProps} />
}

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 (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}
```

### 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 (
    <ERPUIProvider>
      {/* Your components here */}
    </ERPUIProvider>
  );
}
```

---

## 🌐 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
```
