Package, Install and Update a Plugin

How a finished plugin gets onto a site, how it is upgraded, and how it is removed — with the exact commands and the limits of the Plugin Manager.

1. Build the package

A package is a ZIP whose contents are one module folder. Both layouts are accepted by the validator:

testimonials-1.0.0.zip                 testimonials-1.0.0.zip
  Testimonials/            (a)           module.json            (b)
    module.json                          composer.json
    composer.json                        app/ ...
    app/ ...

The archive must contain exactly onemodule.json and it defines the module root; everything must live under that root (multiple_roots otherwise — remove __MACOSX).
Include:module.json, composer.json, app/, config/, database/, lang/, resources/, routes/, and published assets under resources/assets/.
Exclude:tests/, node_modules/, vendor/, .git, editor folders, symlinks (rejected), and files with Windows-reserved names.
Limits: 20 MB upload, 2 500 files, 100 MB uncompressed, 240-character paths (config/plugins.php).

PowerShell — build a ZIP of the sample plugin

$src = "examples\Testimonials"            # from the documentation folder
$tmp = Join-Path $env:TEMP "pkg"; Remove-Item $tmp -Recurse -Force -ErrorAction SilentlyContinue
New-Item -ItemType Directory $tmp | Out-Null
Copy-Item -Recurse $src "$tmp\Testimonials"
Remove-Item "$tmp\Testimonials\tests" -Recurse -Force
Compress-Archive -Path "$tmp\Testimonials" -DestinationPath testimonials-1.0.0.zip

cd /tmp && rm -rf pkg && mkdir pkg && cp -r /path/to/Testimonials pkg/ && rm -rf pkg/Testimonials/tests
(cd pkg && zip -r ../testimonials-1.0.0.zip Testimonials -x '*.DS_Store')

A ready-made testimonials-1.0.0.zip is available to download. It contains the complete example plugin without the tests.

2. Install

Through the Plugin Manager (recommended for site owners)

UploadOpen Appearance → Plugins (permission install plugins), choose Add new and upload the ZIP. The archive is validated and unpacked into a private temporary folder; nothing in it is executed. On success it is moved to Modules/{Name} and listed as inactive.
Refresh the autoloaderOn the server run composer dump-autoload (or composer dump-autoload -o in production). This step is required: the Plugin Manager never runs Composer.
ActivateClick Activate (permission activate plugins). Missing, inactive or out-of-range dependencies are reported next to the plugin.
Migrate and seedRun php artisan migrate, and the plugin's seeder if it has one: php artisan db:seed --class="Modules\Testimonials\Database\Seeders\DatabaseSeeder".
Publish assets (if any)php artisan module:publish Testimonials copies resources/assets to public/modules/testimonials.
Clear cachesphp artisan optimize:clear (the Plugin Manager already does this on every operation).

From the command line (developers and CI)

cp -r Testimonials Modules/Testimonials        # or unzip into Modules/
composer dump-autoload
php artisan module:enable Testimonials
php artisan migrate
php artisan module:publish Testimonials         # only if it ships resources/assets
php artisan optimize:clear
php artisan module:list                          # shows Enabled/Disabled and priority

Command-line commands bypass safeguards

module:enable, module:disable and module:delete are plain nwidart commands: they do not check dependencies, protection or locks. The UI path through PluginManager does.

3. Updating a plugin

The upload flow refuses a plugin that is already installed ("Plugin updates are not supported by this upload flow"). Ship an update as a replacement of the files:

Put the site in maintenance mode if the update changes the database (Settings → Maintenance or php artisan down --secret=...).
Replace the folderDeactivate (optional), replace the contents of Modules/{Name} with the new version, keeping any site-specific files.

Autoload and migrate

composer dump-autoload
php artisan migrate --force
php artisan optimize:clear

Bump the version in module.json so dependants that require a version range ("yourplugin": "^1.2") can tell.
Re-run seeders that are idempotent (template-library seeders, default settings) and republish assets.
Bring maintenance mode down and smoke-test.

Rules that make updates painless:

Never edit an already-released migration. Add a new migration with a later timestamp. Guard with Schema::hasTable / hasColumn when appropriate.
Ship new permissions as migrations (as Booking's add_booking_refund_permissions): they run once per site and assign to the right roles.
Keep setting keys, route names and shortcode ids stable: saved pages contain your shortcode tags, and widgets store your class and settings.
Deprecate rather than remove shortcode attributes: accept old attributes and ignore them (the core's ShortcodeBlog still accepts retired blog layout attributes for exactly this reason).

4. Assets in a distributable plugin

The platform's own Vite build lists every bundled module entry in the root vite.config.js; a plugin installed from a ZIP cannot rely on that. Choose one:

Approach	How	Best for
Static assets	Put compiled CSS/JS/images in `resources/assets`; after install run `php artisan module:publish {Name}`; reference with `asset('modules/{alias}/app.css')` in Blade	ZIP-distributed plugins
Inline in Blade	`@push('page_header')` / `@push('page_scripts')` with small snippets	Tiny additions
Vite entry in the root config	Add the file paths to `input` in `vite.config.js` and run `npm run build`, then `@vite('Modules/{Name}/resources/js/app.js')`	In-repo modules and custom builds
Shortcode assets	Declare `->assets(['vite' => [...], 'styles' => [...], 'scripts' => [...]])` on the shortcode definition; they load only on pages containing the tag	Page-builder blocks

5. Deactivate and remove

Deactivate in the manager: routes, sidebar, widgets, schedules and shortcodes disappear. A saved page that still contains one of your <x-shortcode-*> tags can no longer be compiled by Blade (unknown component). PageSlugRenderer swallows that exception and prints the stored HTML unrendered, so every shortcode on that page stops rendering, not only yours. Warn site owners before deactivating a plugin that provides blocks.
Delete (inactive, unprotected, no dependents) moves the folder to a private trash and removes it. Tables, permissions and settings stay. If you want a clean uninstall, document a command or migration rollback (php artisan migrate:rollback --path=Modules/Testimonials/database/migrations) to run before deleting.
Remove leftover setting rows with Setting::forget('key') + Setting::save() in your own cleanup command.

6. Release checklist

module.json: valid name, alias, description, version, providers, accurate requires.
composer.json: PSR-4 map for app/, database/factories, database/seeders.
All strings in lang/en/*.php (add the other languages you support).
Every named page route has a breadcrumb; every route is permission-gated; route names follow admin.{alias}.*.
Migrations idempotent, permissions in a migration, a factory for each model.
vendor/bin/pint {Module} and vendor/bin/phpstan analyse {Module} pass; tests pass.
No env() calls outside config/; no hard-coded URLs; no {{ }}/@php in data baked into page content.
Assets built and published, or inlined.
Install the ZIP on a clean site, run the activation steps above, and walk through every screen.