Troubleshooting

This guide covers common issues developers encounter when using the Boilerplate App template to create new FlowState applications.

Common Issues

Issue: Dev Server Won't Start

Symptoms:

• yarn dev fails to start
• Port already in use error
• Module not found errors

Cause: Port conflict, missing dependencies, or incorrect configuration.

Solution:

1. Check port availability:

   # See if the port is in use
   lsof -i :3210
   
   # Kill the process if needed
   kill -9 <PID>
   

2. Choose a different port in vite.config.mts:

   export default createViteConfig({
     port: 3215,  // Use an available port in 3200-3299 range
   });
   

3. Reinstall dependencies:

   # From monorepo root
   yarn install
   

Issue: Routes Not Working in Embedded Mode

Symptoms:

• Navigation links don't work when embedded in host
• Routes work in standalone but not embedded
• 404 errors on navigation

Cause: Mismatch between basePath in plugin config and route definitions.

Solution:

1. Verify plugin configuration in src/plugin.ts:

   config: {
     useHostRouter: false,
     basePath: '/myapp',  // Must match your routes
   },
   

2. Check route definitions in src/App.tsx:

   <Routes>
     <Route index element={<Navigate to="home" replace />} />
     <Route path="home" element={<HomePage />} />
     {/* Routes are relative to basePath */}
   </Routes>
   

3. Ensure sidebar links match in src/components/Sidebar.tsx:

   const links = [
     { path: '/home', label: 'Home', icon: 'home' },
     // Paths should be relative to basePath
   ];
   

Issue: Styles Not Loading

Symptoms:

• Tailwind classes not applying
• Unstyled components
• CSS not bundled in build

Cause: Missing CSS imports or incorrect Tailwind configuration.

Solution:

1. Verify CSS import in src/index.ts:

   import './index.css';
   

2. Check Tailwind content paths in tailwind.config.js:

   module.exports = {
     content: [
       './src/**/*.{js,ts,jsx,tsx}',
       './index.html',
     ],
     // ...
   };
   

3. Verify PostCSS configuration in postcss.config.js:

   module.exports = {
     plugins: {
       tailwindcss: {},
       autoprefixer: {},
     },
   };
   

Issue: Build Errors with External Dependencies

Symptoms:

• Build fails with module resolution errors
• Duplicate React instances
• Runtime errors about hooks

Cause: Peer dependencies not marked as external in build config.

Solution:

Update tsup.config.ts to externalize peer dependencies:

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['cjs', 'esm'],
  dts: true,
  external: [
    'react',
    'react-dom',
    'react-router-dom',
    '@epicdm/flowstate-app-framework',
    'lucide-react',
    // Add other peer dependencies here
  ],
});

Issue: Plugin Not Loading in Host

Symptoms:

• App doesn't appear in launcher
• Console errors about missing plugin
• Plugin onLoad never fires

Cause: Plugin not registered in host container or export issues.

Solution:

1. Verify plugin export in src/index.ts:

   export { myappPlugin } from './plugin';
   

2. Register in host (usually in the host app's configuration):

   import { myappPlugin } from '@epicdm/flowstate-app-myapp';
   
   const plugins = [
     // ... other plugins
     myappPlugin,
   ];
   

3. Check package.json exports:

   {
     "exports": {
       ".": {
         "types": "./dist/index.d.ts",
         "import": "./dist/index.mjs",
         "require": "./dist/index.js"
       }
     }
   }
   

Issue: Hot Module Replacement (HMR) Not Working

Symptoms:

• Changes require full page refresh
• Console shows HMR disconnected
• Fast refresh not triggering

Cause: Component structure doesn't support Fast Refresh, or Vite HMR is misconfigured.

Solution:

1. Export components as named exports (not anonymous):

   // Good - supports HMR
   export function HomePage() { ... }
   
   // Bad - may break HMR
   export default function() { ... }
   

2. Keep components in separate files - mixing components and non-component code can break Fast Refresh.

3. Check Vite config uses the React plugin:

   import react from '@vitejs/plugin-react';
   
   export default defineConfig({
     plugins: [react()],
     // ...
   });
   

Issue: TypeScript Errors After Copying Template

Symptoms:

• Type errors on framework imports
• Cannot find module errors
• Declaration file issues

Cause: TypeScript not finding workspace dependencies or stale build artifacts.

Solution:

1. Clean and reinstall:

   # From monorepo root
   rm -rf node_modules
   yarn install
   

2. Build dependencies first:

   yarn nx build @epicdm/flowstate-app-framework
   

3. Check tsconfig.json references:

   {
     "compilerOptions": {
       "moduleResolution": "bundler",
       "strict": true
     }
   }
   

Debugging Tips

Check Plugin Lifecycle

Add logging to verify your plugin loads:

export const myappPlugin: AppPlugin = {
  // ...
  onLoad: async (services) => {
    console.log('[MyApp] Plugin loaded');
    console.log('[MyApp] Available services:', services.getServiceNames());
  },
  onUnload: async () => {
    console.log('[MyApp] Plugin unloaded');
  },
};

Inspect Component Tree

Use React DevTools to:

• Verify FlowstateAppContainer is wrapping your app
• Check props being passed to components
• Inspect context values

Debug Routing

Use React Router DevTools or add a debug component:

import { useLocation } from 'react-router-dom';

function DebugRoute() {
  const location = useLocation();
  console.log('Current path:', location.pathname);
  return null;
}

Check RxDB State

In browser DevTools, check Application > IndexedDB to see RxDB collections and data.

Getting Help

If you can't resolve your issue:

1. Review the Template Structure documentation
2. Check the FAQ for common questions
3. Search existing issues in the monorepo
4. Ask in the development channel with:
   • Description of the issue
   • Steps to reproduce
   • Relevant code snippets
   • Error messages and console output