zero-fucks-given/docs/core/devtools/module-generator/troubleshooting.md

Module Generator Troubleshooting

Generated Files Exist but the Module Is Not Loaded

Docker file watching does not reliably pick up entirely new directories: the backend discovers apps/backend/modules/ routes at startup, and the admin app discovers apps/admin/src/modules/**/config/module.ts through Vite's module registry. Restart both services and reload the admin app:

docker compose restart

Still not loaded? Check logs for TypeScript errors, invalid generated imports, route-loading or manifest errors:

docker compose logs --tail=200 backend admin

(Outside Compose, restart the backend and admin dev processes manually.)

Module Loads but Is Missing from the Menu

Usually a permission mismatch or invalid menu/module configuration. Check in order:

1. Permission slugs match exactly — backend apps/backend/modules/<ModuleName>/config/permissions.ts (e.g. { slug: 'products.view' }) vs frontend apps/admin/src/modules/<name>/config/meta.ts (MODULE_PERMISSION_VIEW = 'products.view'), for view/create/update/delete. Pluralization is heuristic — already-plural or irregular names need manual correction.
2. The current role owns the view permission — the menu filters on MODULE_PERMISSION_VIEW: the permission exists in access control, the role has it with the exact slug, and the session was refreshed after role changes.
3. config/menu.ts — valid exported menu factory, path uses MODULE_ROOT_PATH, permissions contains MODULE_PERMISSION_VIEW, the route exists. The menu is generated with the Datatable asset — without it, add a menu manually or keep the module hidden.
4. config/module.ts — exports a valid AppModuleConfig, unique module ID, not enabled: false, exposes menu, routes, messages.
5. config/routing.tsx — MODULE_ROOT_PATH, the menu path, and the generated route all point to the same URL (a broken route and an invisible menu item are separate problems).

Final Checks

Run npm run build:backend and npm run build:admin to expose generated TypeScript or import errors, then verify: both module directories exist with the selected assets, services were restarted, slugs match, the role has the view permission, and the menu path matches the route. Module discovery errors are reported in backend and admin startup logs.