noerd-module-development

Noerd Module Development

A module is a Composer package under app-modules/{module}/ (namespace Noerd\{Module} by convention) that ships a tenant app: YAML configs, Livewire components, model, migrations, routes, translations, tests and an install/update command. Hard rules: noerd/noerd Boost guideline. Docs: vendor/noerd/noerd/docs/creating-modules.md, make-app.md, navigation.md, artisan-commands.md, traits.md, ai-agents.md.

1. Scaffold

php artisan noerd:make-app        # choose "Module": asks title, name, heroicon, then registers with Composer and installs (tenant assignment is the only question)
php artisan noerd:make-module            # the scaffolder itself: module name, app title, heroicon
                                    # scripted: noerd:make-module inventory --title=Inventory --icon=cube
composer update noerd/{module}
php artisan noerd:install-{module}  # copies YAML, registers the tenant app, migrates (--scaffold = the silent make-app run)
php artisan noerd:make-resource Item --app={module}   # per record type, after model + migration exist in the module

The scaffold is dashboard + plumbing, no model. noerd:make-resource / make-list / make-detail / make-page / make-dashboard detect a module app (app-modules/{app}/composer.json) and write into it: components under {app}::, routes into routes/{app}-routes.php, YAML + navigation into both copies.

Never write the tenant_apps row of a module by hand or via the root noerd:make-app flow — the generated install command registers it (name = UPPERCASE module key, icon = the heroicon from getAppIcon(), route = the module dashboard). A module ships no icon file; a Blade icon is only the manual exception when no heroicon fits.

Generated layout (keep it — do not invent new base folders):

app-modules/{module}/
├── app-configs/{module}/            # YAML templates: lists/, details/, pages/, navigation.yml
├── app-configs/stubs/add_{module}_tenant_app.php.stub   # tenant-app migration published by the install command
├── database/{migrations,factories,seeders}/
├── resources/boost/guidelines/core.blade.php   # module-specific agent rules (Boost)
├── resources/lang/de.json           # English key → German
├── resources/views/components/      # {module}-dashboard.blade.php, *-list.blade.php, *-detail.blade.php, *-page.blade.php, *-modal.blade.php (flat)
├── routes/{module}-routes.php
├── src/{Commands,Models,Providers}/
├── tests/                           # Pest, incl. tests/Traits
├── AGENTS.md + CLAUDE.md            # contributor notes for the module
└── composer.json