admin/docs/devtools/module-generator/troubleshooting.md

Module Generator Troubleshooting

Generated Files Exist but the Module Is Not Loaded

Docker file watching does not always restart the backend or rebuild the admin module registry after the generator creates new directories. Existing file changes may be detected while newly generated module files are not.

Restart both application services manually from the repository root:

docker compose restart

Then reload the admin app. If the module still is not loaded, inspect service logs:

docker compose logs --tail=200 backend admin

Check for TypeScript errors, invalid generated imports, route-loading failures, or module-manifest errors. If the containers are not running through Compose, restart the corresponding backend and admin development processes manually.

The restart is necessary because:

• the backend discovers generated route files under backend/modules/ during startup;
• the admin app discovers apps/admin/src/modules/**/config/module.ts through Vite's module registry;
• adding an entirely new directory may not trigger the same reload behavior as editing an existing file.

Module Loads but Is Missing from the Menu

If generation succeeded and both services restarted, a missing menu item usually indicates a permission mismatch or an invalid menu/module configuration.

1. Compare permission slugs

Check the generated backend permissions:

backend/modules/<ModuleName>/config/permissions.ts

Check the frontend permission constants:

apps/admin/src/modules/<name>/config/meta.ts

The view slug must match exactly. For example:

// backend permissions.ts
{ slug: 'products.view', name: 'Product view' }

// frontend meta.ts
export const MODULE_PERMISSION_VIEW = 'products.view';

Also compare the create, update, and delete slugs. Module-name pluralization is generated heuristically, so names that are already plural or have irregular plurals require manual correction.

2. Verify the current role owns the permission

The menu filters items using MODULE_PERMISSION_VIEW. Confirm that:

• the generated permission is available to the access-control system;
• the current admin role has the generated view permission;
• the role-to-permission assignment uses the same exact slug;
• the session or permission data has been refreshed after changing the role.

3. Check menu configuration

Inspect:

apps/admin/src/modules/<name>/config/menu.ts

Confirm that:

• the exported menu factory is valid;
• path uses MODULE_ROOT_PATH;
• permissions contains MODULE_PERMISSION_VIEW;
• the file is not empty;
• the configured route exists.

The generator creates the menu content with the Datatable frontend asset. If Datatable was not selected, add a menu implementation manually or keep the module intentionally hidden from navigation.

4. Check the module manifest

Inspect:

apps/admin/src/modules/<name>/config/module.ts

The manifest must export a valid AppModuleConfig, must not set enabled: false, and must expose the intended menu, routes, and messages values. Its module ID should be unique.

5. Check route configuration

Inspect:

apps/admin/src/modules/<name>/config/routing.tsx

Confirm that MODULE_ROOT_PATH, the menu path, and the generated route all point to the same URL. A visible menu item with a broken route and an invisible menu item are separate problems; verify both configuration files.

Final Checks

Run both builds to expose generated TypeScript or import errors:

npm run build:backend
npm run build:admin

Then verify:

1. backend/modules/<ModuleName>/ exists and contains the selected backend assets.
2. apps/admin/src/modules/<name>/ exists and contains a valid module manifest.
3. Docker services or local development processes were restarted.
4. Backend and frontend permission slugs match.
5. The current role owns the view permission.
6. The menu path matches the frontend route.

If all checks pass, review the backend and admin logs during startup. Module discovery errors are normally reported there.