nWidart/laravel-modules: splitting a Laravel app into Modules/, and the Composer plugin it all depends on
Module Management In Laravel
At a glance
- What is it?
- laravel-modules turns a large Laravel application into self-contained modules under Modules/, each with its own providers, routes, migrations and config. It works well once set up, but module classes only load if wikimedia/composer-merge-plugin is trusted and configured, and the package major has to match your Laravel major.
- Who is it for?
- laravel-modules suits teams whose Laravel application has grown large enough that grouping routes, controllers, migrations and config per feature is worth an extra layer of Composer configuration. It is not for projects that cannot allow Composer plugins to execute code, because module autoloading runs through wikimedia/composer-merge-plugin.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly PHP, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- nWidart/laravel-modules6,241 β Β· +28
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| nWidart/laravel-modules | 6.2k | 6.2k |
28 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Each module is a small Laravel package living inside Modules/
The package splits a Laravel application into modules stored in Modules/. Each module carries its own service providers, routes, controllers, models, views, migrations, config and translations, and behaves like a small Laravel package inside your app. Running the generator for a module named Blog:
php artisan module:make Blogproduces this layout:
Modules/Blog/
βββ app/ Http/Controllers, Providers
βββ config/
βββ database/ factories, migrations, seeders
βββ resources/ assets, views
βββ routes/ web.php, api.php
βββ tests/ Feature, Unit
βββ composer.json
βββ module.json
βββ package.json
βββ vite.config.jsThree files at the root of the module matter beyond the code folders. composer.json gives each module its own Composer manifest, which is how its classes get autoloaded. module.json holds the module's own metadata. package.json and vite.config.js give it a separate front-end build entry, so a module's assets can be compiled alongside its PHP. The cost of that independence is more files to keep consistent: every module adds another composer.json and another Vite config to your repository.
Module classes only autoload through wikimedia/composer-merge-plugin
Because each module has its own composer.json, the app's root manifest has to pull those files in. That is done by wikimedia/composer-merge-plugin, configured in the extra section of your application's composer.json:
"extra": {
"laravel": {
"dont-discover": []
},
"merge-plugin": {
"include": [
"Modules/*/composer.json"
]
}
},On first install Composer stops and asks whether you trust the plugin to execute code:
Do you trust "wikimedia/composer-merge-plugin" to execute code and wish to enable it now? (writes "allow-plugins" to composer.json) [y,n,d,?]Answer y, or set it yourself:
"config": {
"allow-plugins": {
"wikimedia/composer-merge-plugin": true
}
}The failure mode is quiet but total. If the plugin is set to false, modules are not autoloaded, so the module directories exist and the generators run, yet the classes inside them cannot be found. Organizations that block third-party Composer plugins for policy reasons cannot use the package as designed. After any change to composer.json, regenerate the autoloader:
composer dump-autoloadThe Modules\\ autoload entry became obsolete in v11.0
Older installations carried a manual PSR-4 line in the root composer.json mapping the Modules namespace to the modules directory. Since v11.0, the "Modules\\": "modules/" autoload entry is no longer needed, and the instruction is to remove it from composer.json if it is still present.
This matters most to projects that have upgraded through several majors. A codebase that started on an early release and followed each Laravel version up to 13 can still carry the old entry next to the merge-plugin configuration. Leaving it in place means two mechanisms describing where module classes live, one of which points at a lowercase modules/ path while the generators write to Modules/. Clean it out during the upgrade to v11 or later, then run composer dump-autoload so the generated autoloader reflects only the merge-plugin setup.
The activator decides which modules boot
Every module is either enabled or disabled, and only enabled modules are booted. The state is held by an activator, which by default stores it in a JSON file. Four commands cover the everyday cycle:
php artisan module:make Blog # create a module
php artisan module:list # list modules and their status
php artisan module:disable Blog # stop booting the module
php artisan module:enable Blog # boot it againThe consequence is that whether a feature exists in a running application depends on a piece of state outside your code. Disabling a module stops its providers from booting, so its routes and bindings do not register. With the default JSON file activator, that status is a file on disk, which means each environment carries its own copy. If production and staging disagree about whether Blog is enabled, the same release behaves differently in each. Treat the activator's file as configuration: decide whether it is committed with the code or set per environment, and run module:list after a deploy to confirm the result.
The package major has to match the Laravel major
Version numbers track Laravel. The current line requires PHP 8.3+ and Laravel 13, and the mapping is direct:
| Laravel | laravel-modules | |---------|-----------------| | 13 | ^13.0 | | 12 | ^12.0 | | 11 | ^11.0 | | 10 | ^10.0 |
Older Laravel versions follow the same rule from the other end: Laravel 5.4 uses ^1.0, 5.5 uses ^2.0, and so on through Laravel 9 with ^9.0. The practical consequence is that upgrading Laravel always means changing this constraint in composer.json as well. A project on Laravel 12 that runs composer update will stay on ^12.0, and moving to Laravel 13 also moves the PHP floor to 8.3. The 13.x line is moving quickly: v13.1.0 and v13.2.0 were both tagged on 2026-10-25, v13.3.0 followed on 2026-10-28, and the last push was the same day. CHANGELOG.md in the repository is the place to read what each of those minor releases changed.
The service provider registers itself and the config file is opt-in
Installation is one Composer command:
composer require nwidart/laravel-modulesThe service provider and alias register automatically, so there is no manual edit to the application's provider list. Publishing the package's config file is optional and uses the provider class name:
php artisan vendor:publish --provider="Nwidart\Modules\LaravelModulesServiceProvider"Skipping the publish step keeps you on the package defaults, including the JSON file activator. Publishing gives you a copy of the config in your app to change, at the price of having to compare it against the package's config/ directory when a new major changes the available keys. Neither step replaces the merge-plugin configuration described above: composer require alone installs the package, but modules you generate afterwards still need the extra and allow-plugins entries before their classes load.
Artisan generators and the pingpong/modules lineage
Most day-to-day work happens through Artisan generators. module:make creates a module, and generators such as module:make-controller, module:make-model and module:make-migration create classes inside an existing one, placing them in the module's own app/, database/ and other folders instead of the application's. The full command reference lives in the documentation at https://laravelmodules.com/docs, while the repository's homepage field points to https://docs.laravelmodules.com.
The package was originally based on pingpong/modules, which is no longer maintained. Projects still running on pingpong have a natural successor here, though the module layout and the merge-plugin autoloading need to be checked against an existing tree rather than assumed to match. Credits go to Nicolas Widart, David Carr and gravitano along with other contributors, and the code is MIT-licensed in LICENSE.md. The repository also holds RELEASING.md, cliff.toml, phpstan.neon.dist, phpunit.xml.dist and pint.json, so release steps, static analysis, tests and code style each have a checked-in configuration that contributors can run locally.
Editorial conclusion
laravel-modules suits teams whose Laravel application has grown large enough that grouping routes, controllers, migrations and config per feature is worth an extra layer of Composer configuration. It is not for projects that cannot allow Composer plugins to execute code, because module autoloading runs through wikimedia/composer-merge-plugin. Before adopting it, match the package major to your Laravel major (^13.0 for Laravel 13, which needs PHP 8.3+), add the merge-plugin include for Modules/*/composer.json, and decide where the activator's enabled and disabled status will live in each environment.
Frequently asked questions
laravel modules vs packages
In laravel-modules, each module lives in Modules/ with its own service providers, routes, controllers, models, views, migrations, config and translations, and works like a small Laravel package inside your app. Modules can also be enabled or disabled, and only enabled ones are booted.
Which laravel-modules version should I use with Laravel 12?
Use ^12.0 for Laravel 12. The current ^13.0 line targets Laravel 13 and requires PHP 8.3+.
Why are my laravel-modules classes not autoloading?
laravel-modules autoloads module classes through wikimedia/composer-merge-plugin, which must include Modules/*/composer.json and be allowed in allow-plugins. If the plugin is set to false, modules are not autoloaded; fix the setting and run composer dump-autoload.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/nwidart-laravel-modules)Star history chart for your README
[](https://hysenlabs.com/projects/nwidart-laravel-modules)Was this useful?