README

Laravel Modular is a professional, framework-agnostic modular system engineered for Laravel 11/12/13. It empowers you to build scalable, strictly typed, and decoupled applications with zero configuration overhead.

We override 29+ native Artisan commands to provide a seamless "first-class" modular experience, feeling exactly like standard Laravel but better.

✨ Features

🏗️ Native Experience: 29+ Artisan commands (make:model, make:controller, etc.) fully support --module.
⚡ Zero Config Autoloading: Intelligent composer-merge-plugin integration for isolated module dependencies.
🚦 Topological Sorting: Strict dependency graph resolution ensures base modules always boot before their dependents.
🚀 Performance First: Built-in discovery caching (modular:cache) for near-zero overhead in production.
🔄 Dynamic Activation: Enable or disable modules on the fly via module:enable and module:disable.
🔍 Auto-Discovery: Automatic registration of Artisan commands, Policies, and Event Listeners within modules.
🔌 Decoupled Architecture: Strictly typed ModuleRegistry and traits for maximum stability.
🧭 Production Diagnostics: modular:doctor, modular:status, modular:debug, modular:graph, and modular:why make module state transparent.
🧠 Laravel Boost Ready: Ships package guidelines and a dedicated Boost skill for AI-assisted modular development.
🧩 Migration Friendly: Includes modular:import-nwidart to preview and migrate nwidart-style modules.
✅ Laravel 11, 12 & 13 Ready: Optimized for PHP 8.2+ and the latest framework features.
🎨 Asset Management: Seamless Vite integration via modular_vite() and asset linking.

🌍 Ecosystem

Enhance your modular application with our official packages:

Laravel Hooks: specific modular hook system support.
Filament Integration: Seamless Filament admin panel integration in modules.
Livewire Integration: First-class Livewire component support in modules.
Laravel Themer: Advanced theme management system.

🚀 Installation

Install the package via Composer:

composer require alizharb/laravel-modular

Preview the installer without writing files:

php artisan modular:install --dry-run

Run the installation command to automatically configure your application:

php artisan modular:install

Note: This will automatically install and configure wikimedia/composer-merge-plugin to handle your module dependencies.

Manual Setup

If you prefer to configure things manually, follow these steps:

1. Composer Autoloading Add the following to your root composer.json to ensure module namespaces are autoloaded:

"autoload": {
    "psr-4": {
        "App\\": "app/",
        "Modules\\": "modules/"
    }
},
"extra": {
    "merge-plugin": {
        "include": [
            "modules/*/composer.json"
        ]
    }
}

2. Vite Configuration To enable hot-reloading for module assets, create a vite.modular.js file in your root and update vite.config.js:

// vite.config.js
import { defineConfig } from "vite";
import laravel from "laravel-vite-plugin";
import { modularLoader } from "./vite.modular.js";

export default defineConfig({
    plugins: [
        laravel({
            input: [
                "resources/css/app.css",
                "resources/js/app.js",
                ...modularLoader.inputs(), // Add this line
            ],
            refresh: [
                ...modularLoader.refreshPaths(), // Add this line
            ],
        }),
    ],
});

📖 Usage

Creating a Module

Generate a fully structured module in seconds:

php artisan make:module Blog

Generating Resources

Every standard Laravel make: command acts as a modular command when you pass the --module flag:

# Create a Model with Migration, Controller, and Factory in 'Blog' module
php artisan make:model Post --module=Blog -mcf

# Create a resource controller
php artisan make:controller API/PostController --module=Blog --api

# Create a request, policy, and test inside the module
php artisan make:request StorePostRequest --module=Blog
php artisan make:policy PostPolicy --module=Blog --model=Post
php artisan make:test PostFeatureTest --module=Blog

Modular Database

Run migrations and seeders specifically for your modules:

# Migrate all modules
php artisan modular:migrate

# Migrate a specific module
php artisan modular:migrate Blog --fresh --seed

# Rollback a module's migrations
php artisan modular:migrate Blog --rollback --step=2

# Run module seeders
php artisan modular:seed Blog

Module Management & Utilities

# List all modules and discovered resources
php artisan modular:list

# Visualize module dependencies in an ASCII tree
php artisan modular:list --tree

# Diagnose common configuration issues and view Health Scores
php artisan modular:doctor

# Output diagnostics for CI, dashboards, and automation
php artisan modular:doctor --json

# Safely repair missing infrastructure and refresh stale cache
php artisan modular:doctor --fix

# View project-level modular health
php artisan modular:status
php artisan modular:status --json

# Sync module dependencies to root composer.json
php artisan modular:sync

# Export a module to a standalone Composer package
php artisan modular:export Blog --path=packages/blog

# Run npm commands for a module (Workspaces)
php artisan modular:npm Blog install
php artisan modular:npm Blog build

# Check for circular dependencies and conflicts
php artisan modular:check

# Debug module configuration
php artisan modular:debug Blog
php artisan modular:debug Blog --json

# Render a dependency graph
php artisan modular:graph
php artisan modular:graph --format=dot

# Explain why a module exists and what it provides
php artisan modular:why Blog

# Refresh module discovery cache
php artisan modular:refresh

# Preview or import nwidart-style modules
php artisan modular:import-nwidart --dry-run
php artisan modular:import-nwidart Blog --from=NwidartModules

# Run module tests
php artisan modular:test Blog

Blade Directives

Use our dedicated Blade directives to conditionally render UI based on module availability:

@moduleEnabled('Blog')
    <a href="{{ route('blog.index') }}">Read the Blog</a>
@endmoduleEnabled

@moduleDisabled('Store')
    <p>Our store is currently offline.</p>
@endmoduleDisabled

🏎️ Performance Optimization

For maximum production performance, we recommend the following:

Optimized PSR-4: Ensure "Modules\\": "modules/" is in your root composer.json. modular:install handles this for you.
Dependency Syncing: Use php artisan modular:sync to merge module dependencies into your root composer.json and disable the merge-plugin.
Discovery Caching: Always run php artisan modular:cache in your deployment pipeline.
Cache Refreshing: Use php artisan modular:refresh when deployments reuse build artifacts or cache directories.
Health Checks: Run php artisan modular:doctor --json in CI or deployment validation.

modular:cache stores module metadata, statuses, discovered resources, manifest hashes, dependency hashes, provider lists, and a cache timestamp. modular:doctor warns when cached module manifests no longer match disk.

Middleware & Config

Define middleware in your module.json:

"middleware": {
    "web": ["Modules\\Blog\\Http\\Middleware\\TrackVisits"],
    "blog.admin": "Modules\\Blog\\Http\\Middleware\\AdminGuard"
}

Access config case-insensitively:

// Both work!
config('Blog::settings.key');
config('blog::settings.key');

Module Manifest

Every module is described by module.json. In v1.2.0, manifests are validated by modular:doctor and exposed through JSON diagnostics.

{
    "name": "Blog",
    "namespace": "Modules\\Blog\\",
    "provider": "Modules\\Blog\\Providers\\BlogServiceProvider",
    "version": "1.2.0",
    "requires": [],
    "conflicts": [],
    "provides": ["publishing"],
    "removable": true,
    "disableable": true
}

Use requires for dependency ordering, conflicts for modules that cannot be enabled together, and provides for capabilities a module exposes to the application.

Lifecycle Events

Laravel Modular dispatches lifecycle events for integrations, dashboards, logs, and automation:

ModuleEnabling
ModuleEnabled
ModuleDisabling
ModuleDisabled
ModularCached
ModularRefreshed

🧠 Laravel Boost Support

Laravel Modular ships first-class Laravel Boost resources:

resources/boost/guidelines/core.blade.php
resources/boost/skills/laravel-modular-development/SKILL.md

After installing Laravel Boost in an application, run:

php artisan boost:install

If Laravel Modular was installed after Boost, rediscover package resources:

php artisan boost:update --discover

Boost-aware agents will learn to use native make:* --module commands, respect module boundaries, validate module.json, and run the right diagnostics.

🛠️ Helpers & Assets

Global Helpers

Access module information globally with strictly typed helpers:

// Get the registry or specific module config
$modules = module();
$blogConfig = module('Blog');

// Get absolute path to a resource
$viewPath = module_path('Blog', 'Resources/views');

// Get absolute path to a config file
$configPath = module_config_path('Blog', 'settings.php');

Asset Management

Link your module assets to public/modules for easy serving:

php artisan modular:link

Use the helper to generate asset URLs in your Blade views:

<link rel="stylesheet" href="{{ module_asset('Blog', 'css/app.css') }}">
<img src="{{ module_asset('Blog', 'images/logo.png') }}" alt="Blog Logo">

⚙️ Configuration

Publish the configuration file for advanced customization:

php artisan vendor:publish --tag="modular-config"

You can customize:

Paths: Move modules to packages/ or any custom directory.
Composer: Set default fields (vendor, author, license) for generated composer.json files.
Activator: Swap the default module activator for your own implementation.

🧪 Testing

We strictly enforce testing. Use the provided test suite to verify your modules:

vendor/bin/pest

For module-level testing:

php artisan modular:test Blog

🌍 Ecosystem

Extend your modular architecture with our official ecosystem packages:

Package	Description
Laravel Themer	For advanced theme management support
Modular Livewire	Provides automatic Livewire component discovery and registration within modules.
Modular JS	Enables JS discovery within modular structures and provides zero-config autoloading for modules.
Modular Filament	Enables Filament v5 admin panel integration with automatic discovery in modules.
Filament Themer Launcher	Provides a comprehensive Filament v5 interface for managing and switching themes.
Filament Modular Launcher	A powerful Filament v5 manager for listing, toggling, and backing up system modules.
Laravel Hooks	Adds a universal extensibility and plugin system for Laravel applications.

⚡ JavaScript & Vite Integration

We provide first-class support for modern frontend tooling:

NPM Workspaces: Run php artisan modular:npm to configure workspaces, allowing each module to manage its own package.json dependencies efficiently.
Vite Integration: Use the modular_vite('ModuleName') helper to load module-specific assets with full Hot Module Replacement (HMR) support.
Asset Publishing: Easily publish public assets to the main application with php artisan modular:link.

🔄 Migrating From nwidart/laravel-modules

Laravel Modular v1.2.0 includes a dry-run importer for teams evaluating a move from nwidart/laravel-modules:

php artisan modular:import-nwidart --dry-run
php artisan modular:import-nwidart Blog --from=NwidartModules

The importer is intentionally safe: preview first, import deliberately, then run:

php artisan modular:refresh
php artisan modular:doctor
php artisan modular:check

Read the full guide: Migration From nwidart.

📚 Documentation

For a copy-ready release note, see RELEASE_NOTES_1.2.0.md.

💖 Sponsors

We would like to extend our thanks to the following sponsors for funding Laravel Modular development. If you are interested in becoming a sponsor, please visit the Laravel Modular GitHub Sponsors page.

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING for details.

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

🌟 Acknowledgments

Laravel: For creating the most elegant PHP framework.
Spatie: For setting the standard on Laravel package development.

🔒 Security

If you discover any security-related issues, please email Ali Harb at harbzali@gmail.com.

Please see SECURITY for the full security policy.

📄 License

The MIT License (MIT). Please see License File for more information.

Made with ❤️ by Ali Harb

alizharb / laravel-modular

Maintainers

Package info

Fund package maintenance!

Statistics

Security

README

✨ Features

🌍 Ecosystem

🚀 Installation

Manual Setup

📖 Usage

Creating a Module

Generating Resources

Modular Database

Module Management & Utilities

Blade Directives

🏎️ Performance Optimization

Middleware & Config

Module Manifest

Lifecycle Events

🧠 Laravel Boost Support

🛠️ Helpers & Assets

Global Helpers

Asset Management

⚙️ Configuration

🧪 Testing

🌍 Ecosystem

⚡ JavaScript & Vite Integration

🔄 Migrating From nwidart/laravel-modules

📚 Documentation

💖 Sponsors

🤝 Contributing

🌟 Acknowledgments

🔒 Security

📄 License