@machinemetrics/mm-react-components 0.2.3-2 → 0.2.3-20

package/agent-docs/init-troubleshooting.md

@@ -0,0 +1,550 @@
+# Troubleshooting Guide: MachineMetrics React Components Initialization
+
+## Common Issues and Solutions
+
+### 1. Script Execution Issues
+
+#### Error: `npx: command not found`
+
+**Cause**: NPX not installed or not in PATH.
+
+**Solution**:
+
+```bash
+# Install NPX globally
+npm install -g npx
+
+# Or use npm directly
+npm init @machinemetrics/mm-react-components
+
+# Alternative: Use the package directly
+npx @machinemetrics/mm-react-components init
+```
+
+#### Error: `Permission denied`
+
+**Cause**: Insufficient permissions to execute the script.
+
+**Solution**:
+
+```bash
+# Fix npm permissions
+sudo chown -R $(whoami) ~/.npm
+
+# Or use a Node version manager
+nvm install node
+nvm use node
+```
+
+#### Error: `Network timeout` or `ECONNRESET`
+
+**Cause**: Network connectivity issues or npm registry problems.
+
+**Solution**:
+
+```bash
+# Clear npm cache
+npm cache clean --force
+
+# Use different registry
+npm config set registry https://registry.npmjs.org/
+
+# Retry with verbose output
+npx @machinemetrics/mm-react-components init --verbose
+```
+
+### 2. Dependency Installation Issues
+
+#### Error: `Cannot find module '@machinemetrics/mm-react-components'`
+
+**Cause**: Package installation failed or incomplete.
+
+**Solution**:
+
+```bash
+# Clear cache and reinstall
+npm cache clean --force
+rm -rf node_modules package-lock.json
+npm install
+
+# Install the package specifically
+npm install @machinemetrics/mm-react-components@latest
+
+# Verify installation
+npm list @machinemetrics/mm-react-components
+```
+
+#### Error: `Peer dependency warnings`
+
+**Cause**: Missing or incompatible peer dependencies.
+
+**Solution**:
+
+```bash
+# Install all peer dependencies
+npm install class-variance-authority clsx tailwind-merge @radix-ui/react-slot lucide-react
+
+# Install build dependencies
+npm install -D tailwindcss autoprefixer postcss
+
+# Check for version conflicts
+npm ls
+```
+
+#### Error: `EACCES: permission denied`
+
+**Cause**: File system permission issues.
+
+**Solution**:
+
+```bash
+# Fix npm permissions
+sudo chown -R $(whoami) ~/.npm
+sudo chown -R $(whoami) /usr/local/lib/node_modules
+
+# Or use a Node version manager
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+nvm install node
+nvm use node
+```
+
+### 3. Configuration Issues
+
+#### Error: `Cannot find module 'tailwindcss'`
+
+**Cause**: Tailwind CSS not installed or not configured.
+
+**Solution**:
+
+```bash
+# Install Tailwind CSS
+npm install -D tailwindcss
+
+# Initialize Tailwind
+npx tailwindcss init -p
+
+# Update tailwind.config.js
+module.exports = {
+  content: [
+    "./src/**/*.{js,ts,jsx,tsx}",
+    "./node_modules/@machinemetrics/mm-react-components/dist/**/*.{js,ts,jsx,tsx}",
+  ],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+}
+```
+
+#### Error: `PostCSS plugin tailwindcss requires Tailwind CSS`
+
+**Cause**: PostCSS configuration missing or incorrect.
+
+**Solution**:
+
+```bash
+# Install PostCSS dependencies
+npm install -D postcss autoprefixer
+
+# Create postcss.config.js
+echo "module.exports = {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}" > postcss.config.js
+```
+
+#### Error: `Cannot resolve dependency 'lucide-react'`
+
+**Cause**: Icon library not installed.
+
+**Solution**:
+
+```bash
+# Install Lucide React
+npm install lucide-react
+
+# Verify installation
+npm list lucide-react
+```
+
+### 4. Build and Runtime Issues
+
+#### Error: `Module not found: Can't resolve 'clsx'`
+
+**Cause**: Utility library not installed.
+
+**Solution**:
+
+```bash
+# Install required utilities
+npm install clsx tailwind-merge class-variance-authority
+
+# Verify installation
+npm list clsx tailwind-merge class-variance-authority
+```
+
+#### Error: `Cannot find module '@radix-ui/react-slot'`
+
+**Cause**: Radix UI primitives not installed.
+
+**Solution**:
+
+```bash
+# Install Radix UI dependencies
+npm install @radix-ui/react-slot
+
+# Install additional Radix UI packages if needed
+npm install @radix-ui/react-dialog @radix-ui/react-dropdown-menu
+```
+
+#### Error: `Components not styling correctly`
+
+**Cause**: CSS not imported or theme not applied.
+
+**Solution**:
+
+```tsx
+// Ensure CSS is imported in your main file
+import '@machinemetrics/mm-react-components/themes/carbide';
+
+// Ensure carbide class is applied to root element
+function App() {
+  return (
+    <div className="carbide">
+      <YourApp />
+    </div>
+  );
+}
+```
+
+### 5. Framework-Specific Issues
+
+#### Next.js Issues
+
+**Error**: `Module not found: Can't resolve '@machinemetrics/mm-react-components'`
+
+**Solution**:
+
+```javascript
+// next.config.js
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  transpilePackages: ['@machinemetrics/mm-react-components'],
+};
+
+module.exports = nextConfig;
+```
+
+**Error**: `CSS not loading in production`
+
+**Solution**:
+
+```tsx
+// pages/_app.tsx
+import '@machinemetrics/mm-react-components/themes/carbide';
+import '../styles/globals.css';
+```
+
+#### Vite Issues
+
+**Error**: `Build fails with CSS errors`
+
+**Solution**:
+
+```javascript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  css: {
+    postcss: {
+      plugins: [require('tailwindcss'), require('autoprefixer')],
+    },
+  },
+});
+```
+
+#### Create React App Issues
+
+**Error**: `Tailwind CSS not working`
+
+**Solution**:
+
+```bash
+# Install CRACO for Tailwind support
+npm install -D @craco/craco
+
+# Create craco.config.js
+module.exports = {
+  style: {
+    postcss: {
+      plugins: [
+        require('tailwindcss'),
+        require('autoprefixer'),
+      ],
+    },
+  },
+}
+```
+
+### 6. TypeScript Issues
+
+#### Error: `Cannot find module '@machinemetrics/mm-react-components' or its corresponding type declarations`
+
+**Cause**: TypeScript types not found.
+
+**Solution**:
+
+```bash
+# Install TypeScript dependencies
+npm install -D @types/react @types/react-dom typescript
+
+# Update tsconfig.json
+{
+  "compilerOptions": {
+    "types": ["@machinemetrics/mm-react-components"]
+  }
+}
+```
+
+#### Error: `Property 'className' does not exist on type`
+
+**Cause**: TypeScript configuration issues.
+
+**Solution**:
+
+```tsx
+// Ensure proper imports
+import { Button } from '@machinemetrics/mm-react-components';
+import { cn } from '@machinemetrics/mm-react-components';
+
+// Use proper typing
+interface ButtonProps {
+  className?: string;
+  children: React.ReactNode;
+}
+```
+
+### 7. Performance Issues
+
+#### Issue: `Bundle size too large`
+
+**Cause**: Importing entire library instead of specific components.
+
+**Solution**:
+
+```tsx
+// Import only needed components
+import { Button, Input } from '@machinemetrics/mm-react-components';
+
+// Instead of
+import * as Components from '@machinemetrics/mm-react-components';
+```
+
+#### Issue: `Slow build times`
+
+**Cause**: Inefficient build configuration.
+
+**Solution**:
+
+```javascript
+// webpack.config.js
+module.exports = {
+  optimization: {
+    usedExports: true,
+    sideEffects: false,
+  },
+  resolve: {
+    alias: {
+      '@machinemetrics/mm-react-components': path.resolve(
+        __dirname,
+        'node_modules/@machinemetrics/mm-react-components',
+      ),
+    },
+  },
+};
+```
+
+### 8. Development Server Issues
+
+#### Issue: `Hot reload not working`
+
+**Cause**: File watching issues or configuration problems.
+
+**Solution**:
+
+```bash
+# Clear cache and restart
+npm run dev -- --force
+
+# Check file permissions
+ls -la src/
+
+# Verify file structure
+tree src/
+```
+
+#### Issue: `CSS not updating`
+
+**Cause**: CSS processing issues.
+
+**Solution**:
+
+```bash
+# Restart development server
+npm run dev
+
+# Clear build cache
+rm -rf .next dist build
+
+# Verify PostCSS configuration
+cat postcss.config.js
+```
+
+### 9. Production Build Issues
+
+#### Error: `Build fails in production`
+
+**Cause**: Production-specific configuration issues.
+
+**Solution**:
+
+```bash
+# Check build logs
+npm run build 2>&1 | tee build.log
+
+# Verify environment variables
+echo $NODE_ENV
+
+# Test production build locally
+npm run build && npm run preview
+```
+
+#### Error: `CSS not loading in production`
+
+**Cause**: CSS processing or import issues.
+
+**Solution**:
+
+```tsx
+// Ensure CSS is imported in production
+import '@machinemetrics/mm-react-components/themes/carbide';
+
+// Check build output
+ls -la dist/
+```
+
+### 10. Debugging Tools
+
+#### Enable Verbose Logging
+
+```bash
+# Run with verbose output
+npx @machinemetrics/mm-react-components init --verbose
+
+# Check npm logs
+npm config get loglevel
+npm config set loglevel verbose
+```
+
+#### Check Dependencies
+
+```bash
+# List all dependencies
+npm list --depth=0
+
+# Check for conflicts
+npm ls --depth=0
+
+# Verify package integrity
+npm audit
+```
+
+#### Debug Build Process
+
+```bash
+# Build with debug info
+npm run build -- --debug
+
+# Check webpack stats
+npm run build -- --analyze
+```
+
+## Prevention Strategies
+
+### 1. Environment Setup
+
+```bash
+# Use Node version manager
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+nvm install --lts
+nvm use --lts
+
+# Verify Node and npm versions
+node --version
+npm --version
+```
+
+### 2. Project Structure
+
+```
+my-project/
+├── src/
+│   ├── index.css
+│   ├── App.tsx
+│   └── main.tsx
+├── tailwind.config.js
+├── postcss.config.js
+├── package.json
+└── node_modules/
+```
+
+### 3. Dependency Management
+
+```bash
+# Use exact versions for critical dependencies
+npm install @machinemetrics/mm-react-components@latest
+
+# Lock dependency versions
+npm shrinkwrap
+```
+
+### 4. Configuration Validation
+
+```bash
+# Validate configuration files
+npx tailwindcss --help
+npx postcss --help
+
+# Check for syntax errors
+node -c tailwind.config.js
+node -c postcss.config.js
+```
+
+## Getting Help
+
+### Documentation
+
+- [Component Library Docs](https://components.machinemetrics.com)
+- [Setup Guide](https://components.machinemetrics.com/setup)
+- [Troubleshooting](https://components.machinemetrics.com/troubleshooting)
+
+### Community Support
+
+- [GitHub Issues](https://github.com/machinemetrics/mm-react-components/issues)
+- [Discord Community](https://discord.gg/machinemetrics)
+- [Stack Overflow](https://stackoverflow.com/questions/tagged/machinemetrics)
+
+### Professional Support
+
+- [MachineMetrics Support](https://support.machinemetrics.com)
+- [Enterprise Support](https://enterprise.machinemetrics.com)
+- [Consulting Services](https://consulting.machinemetrics.com)
+
+## Conclusion
+
+This troubleshooting guide covers the most common issues encountered during MachineMetrics React Components initialization. Follow the solutions provided and use the debugging tools to resolve any issues. For additional help, refer to the documentation or contact support.