Installation

Requirements#

The panel frontend ships prebuilt (dist/), so your application does not need Node.js. The panel uses its own client bundle and disables Inertia SSR for its routes.

Installing#

composer require maxcxam/larsadmin
php artisan larsadmin:install

larsadmin:install does the following, in order:

1. publishes the config (larsadmin-config) to config/larsadmin.php;
2. publishes the assets (larsadmin-assets) to public/vendor/larsadmin, overwriting existing files;
3. publishes the service provider (larsadmin-provider) to app/Providers/LarsadminServiceProvider.php and adds it to bootstrap/providers.php;
4. publishes the package migrations (larsadmin-migrations) to database/migrations: the audit log and the background action runs;
5. copies lang/uk/validation.php, only if that file does not exist yet (an existing file is left untouched).

The migration is not run: the audit log is off by default. To turn it on, run php artisan migrate, define the viewLarsadminAudit gate and set LARSADMIN_AUDIT=true (see Audit log).

Notifications and background actions are off as well. To turn them on, create the notifications table (php artisan make:notifications-table), run php artisan migrate, set LARSADMIN_NOTIFICATIONS=true, run a queue worker and schedule larsadmin:prune-notifications (see Notifications and background actions).

The panel is then available at /admin (see the path key below).

AI assistants (optional)#

The package ships a guideline, 15 skills and a local MCP server for AI assistants (Claude Code, Cursor and others). With Laravel Boost 2.x they are installed by php artisan boost:install, without it by php artisan larsadmin:ai. The MCP server needs composer require laravel/mcp --dev; it runs locally only and never in production. See AI assistants.

Updating the package#

composer update maxcxam/larsadmin
php artisan larsadmin:publish

larsadmin:publish publishes the config (an existing file is overwritten only with --force) and always overwrites the assets. The assets are more than app.js and app.css: since 1.5 app.js is only a small entry module, while the panel code, Vue and Inertia live in chunks/ (shared-*, vue-*, inertia-*, plus the bell and the realtime client, which load on demand), and the modules for extensions in runtime/. Publish the whole directory, not single files.

Security fixes ship as patch versions of the latest 1.x release, so keep the package up to date. Report vulnerabilities privately, not in public issues: see SECURITY.md.

Publish tags#

php artisan vendor:publish --tag=larsadmin-lang

larsadmin:install does not publish the larsadmin-lang tag. Publish it when you want to change the translations (see Localization).

Artisan commands#

Configuration (config/larsadmin.php)#

Warning. When allow_local is true and APP_ENV=local, every authenticated user gets into the panel. Do not run shared or public servers with APP_ENV=local, or set LARSADMIN_ALLOW_LOCAL=false.

Example production .env:

LARSADMIN_NAME="Моя адмінка"
LARSADMIN_PATH=backoffice
LARSADMIN_ALLOW_LOCAL=false

Login#

The panel has its own login page (/admin/login) with rate limiting: 5 attempts per minute per email + IP pair and 30 per minute per IP.

Content Security Policy#

If the application sets a CSP, turn on nonces with the standard Vite::useCspNonce() in a middleware that runs before panel pages render: the theme inline script, the extensions' import map, the app.js tag and the modulepreload tags get a nonce attribute. Without a nonce a strict CSP blocks the import map and extensions do not load (the panel works). Example: Extensions: CSP and nonces.

Route cache#

If your application uses php artisan route:cache, rebuild the cache after changing path or domain. The package does not register its routes while the route cache is active.

Next: Entities.

Developing the package#

In the root of the package repository:

resources/js/i18n/uk.json must be committed: run npm run i18n after changing lang/uk/ui.php. dist/ is committed too. CI checks that dist/ is up to date (git diff --exit-code dist after the build).

tests/Ai checks the skills (resources/boost/skills): every guide page, larsadmin:* command, config key, LARSADMIN_* variable and public class must be mentioned in a skill, and everything the skills mention must exist. So new or changed public API updates its skill in the same PR. Every guide page must exist both in docs/guide/ and in docs/guide/en/.