Module Packaging & Distribution

This guide covers how to build a module for distribution, create a marketplace-ready ZIP package, and manage module versions.

Build Pipeline#

The build pipeline compiles assets, installs dependencies, and creates a distributable ZIP:

1. Composer Install (--no-dev)
2. npm Install
3. Asset Compilation (Vite + Tailwind)
4. Pre-compiled Asset Verification
5. ZIP Creation with Manifest

Quick Start#

# Full build + package (recommended)
php artisan module:zip CRM

# Just compile CSS/JS
php artisan module:compile-css CRM --minify

# Just create ZIP (skip build steps)
php artisan module:package CRM

Asset Compilation#

module:compile-css#

Compiles module CSS/JS assets using Vite.

# Development (with hot reload)
php artisan module:compile-css CRM --watch

# Production (minified)
php artisan module:compile-css CRM --minify

# Distribution build (assets inside module directory)
php artisan module:compile-css CRM --minify --dist

Option	Description
--watch	Live reload mode for development
--minify	Production minification
--dist	Build for distribution (output to modules/{Module}/dist/)

Build Output#

Mode	Output Directory	Use Case
Development	public/build-{module}/	Local development
Distribution	modules/{Module}/dist/build-{module}/	Self-contained for ZIP

Vite Configuration#

Each module needs vite.config.js. See the Tailwind Prefixing Guide for the full Vite setup.

Module Packaging#

module:package#

Creates a ZIP file from an existing module (no build step).

php artisan module:package CRM

# With options
php artisan module:package CRM --compile --minify --output=./releases/ --no-vendor

Option	Description
--compile	Compile assets before packaging
--minify	Minify assets during compilation
--output=path	Custom output directory
--no-vendor	Exclude vendor directory from ZIP

module:zip#

Full build pipeline + packaging (recommended for releases).

php artisan module:zip CRM

# Skip steps for faster builds
php artisan module:zip CRM --skip-composer --skip-npm
php artisan module:zip CRM --skip-compile
php artisan module:zip CRM --no-minify --no-vendor

Option	Description
--skip-composer	Skip composer install step
--skip-npm	Skip npm install step
--skip-compile	Skip asset compilation
--no-minify	Don't minify assets
--no-vendor	Exclude vendor directory
--output=path	Custom output path

Output#

modules/crm-v1.1.1.zip

The ZIP filename follows the pattern: {module-slug}-v{version}.zip

Excluded from ZIP#

The packager automatically excludes:

• .git/
• node_modules/
• tests/
• .env
• vendor/ (optional, via --no-vendor)

Module Manifest#

Each ZIP includes .module-manifest.json with build metadata:

{
    "name": "crm",
    "version": "1.1.1",
    "built_at": "2026-03-29T10:30:00+00:00",
    "php_version": "8.3.0",
    "laravel_version": "13.0.0"
}

Module Dependencies#

Composer Dependencies#

Modules can have their own composer.json:

# Install module dependencies
php artisan module:install-deps CRM

# Update module dependencies
php artisan module:update-deps CRM

# Run any composer command in module context
php artisan module:composer CRM require "package/name"

npm Dependencies#

Modules with package.json need npm install before asset compilation:

cd modules/CRM && npm install

The module:zip command handles this automatically.

Versioning#

module.json#

Version is declared in module.json:

{
    "name": "crm",
    "title": "CRM",
    "version": "1.1.1",
    "min_laradashboard_required": "1.0.0",
    "author": "Lara Dashboard",
    "author_url": "https://laradashboard.com/"
}

Version Compatibility#

The min_laradashboard_required field ensures modules only load on compatible LaraDashboard versions. The bootstrap system (bootstrap/modules.php) checks this before loading any module.

Marketplace Assets#

For marketplace listing, include these in your module:

marketplace-assets/ Directory#

modules/{Module}/
├── marketplace-assets/
│   ├── logo.png          ← 256x256 module icon
│   ├── banner.png        ← 1200x400 banner image
│   └── screenshots/
│       ├── 1.png         ← Feature screenshots
│       ├── 2.png
│       └── 3.png
└── README.md             ← Marketplace description

Extended module.json Fields#

{
    "name": "crm",
    "title": "CRM",
    "description": "Complete customer relationship management with contacts, deals, tickets, and AI.",
    "keywords": ["crm", "customer", "management", "contacts", "deals"],
    "category": "core",
    "priority": 20,
    "icon": "lucide:headphones",
    "version": "1.1.1",
    "min_laradashboard_required": "1.0.0",
    "author": "Lara Dashboard",
    "author_url": "https://laradashboard.com/",
    "demo_url": "https://demo.laradashboard.com/",
    "documentation_url": "https://docs.laradashboard.com/modules/crm",
    "providers": [
        "Modules\\Crm\\Providers\\CrmServiceProvider"
    ]
}

Pre-Release Checklist#

Before packaging a module for distribution:

• Update version in module.json
• Update min_laradashboard_required if needed
• All tests pass: php artisan test modules/{Module}/tests/
• Code style: vendor/bin/pint --dirty
• No debug code (dd(), dump(), Log::debug())
• No hardcoded URLs or paths
• Migrations have down() methods
• Permissions migration uses PermissionService
• README.md is up to date
• CLAUDE.md exists for AI assistance
• Marketplace assets (logo, banner, screenshots) included
• Assets compile without errors: php artisan module:compile-css {Module} --minify

Release Workflow#

# 1. Run tests
php artisan test modules/CRM/tests/

# 2. Fix code style
vendor/bin/pint --dirty

# 3. Build and package
php artisan module:zip CRM

# 4. Output: modules/crm-v1.1.1.zip
# Ready for marketplace upload

Next Steps#

• Module Development — Creating modules
• Tailwind Prefixing — CSS asset setup
• CRUD Generator — Scaffold CRUD features
• Testing — Writing module tests