Vilt Cms Laravel Package

Getting Started

Vilt CMS is a full-stack Laravel CMS layer (Laravel + Inertia + Vue + Tailwind) rather than a pure backend package — expect to touch Composer, npm, and the frontend build before you see anything useful.

1. composer require simon-roland/vilt-cms
2. Run the package install command (php artisan vilt:install in v1.x — confirm the exact signature against the repo's README, as installer commands have shifted between minor releases). This publishes config, migrations, and frontend scaffolding.
3. php artisan migrate, then create an admin user (seeder or the installer prompt).
4. npm install && npm run dev, then hit the admin path defined in config/vilt.php (typically /vilt, configurable).
5. php artisan storage:link if you plan to use the media library.

Where to look first: config/vilt.php (routes, middleware/guard, locales, media disks), the published Vue pages/components directory, and the package's block/template registration point. Skim the migrations before running them on anything non-local — they define the content schema you'll be extending.

First use case: a "Pages" resource where an editor composes a page from blocks (hero, rich text, image + caption). That exercises the three things you'll use daily: resource CRUD, block composition, and media handling.

Implementation Patterns

Blocks as the unit of work. Day-to-day Vilt development is mostly defining blocks: a PHP definition (fields, labels, validation) paired with a Vue component for rendering/editing. Keep the PHP definition and the Vue component in the same PR and name them consistently — drift between the two is the most common source of "field renders but doesn't save" bugs.

Publish, don't patch. Override behaviour by publishing config, migrations, and views/components and editing the published copies. Treat vendor/simon-roland/vilt-cms as read-only; anything you edit there vanishes on the next composer update.

Inertia-aware integration. If the rest of your app is Blade, keep Vilt's admin on its own route prefix and middleware group rather than blending Inertia pages into existing controllers. If your app is already Inertia/Vue, share a single Vite entry and resolve page components from one directory so you don't ship two Vue runtimes.

Media pipeline. Configure the disk and any conversions/thumbnails in config rather than in block components, so changing an image size is a config diff and not a hunt through templates. Add a queued conversion job if you're generating large derivatives.

Deployment. Because the admin is Vue-compiled, your deploy pipeline must run npm ci && npm run build alongside composer install --no-dev. Sequence: build → config:cache → route:cache → view:cache → migrate --force. Re-publish tagged assets if the release touched them (see below).

Testing. Feature-test admin routes with RefreshDatabase and an authenticated user against the configured guard; assert Inertia props rather than rendered HTML. Keep a couple of smoke tests per block type so schema changes fail loudly.

Version control. Pin exactly ("simon-roland/vilt-cms": "1.1.5") and upgrade deliberately. This release ships no notes beyond a diff link, so the comparison URL is the only changelog you get.

Gotchas and Tips

v1.1.5 has no usable changelog. The release body is a bare compare link — no breaking changes, features, or deprecations are documented. Treat it as a low-risk patch, but read the diff (v1.1.4...v1.1.5) before upgrading production, and specifically check whether migrations, published assets, or config keys changed. If the diff is frontend-only, a rebuild is still required.

Re-publish after upgrades. Published config and compiled/published frontend assets don't update themselves. After any version bump, diff the package's stubs against your published copies before overwriting — you'll lose customisations otherwise.

Stale caches mask upgrades. config:cache and route:cache will happily serve the old route table after a package update. Always php artisan optimize:clear when behaviour looks impossible.

Auth guard mismatches. If your app uses a non-default guard or a custom user model, set it in config before logging into the admin; the package routes will otherwise resolve the wrong provider and bounce you to login in a loop.

Inertia debugging. Failed Inertia requests return JSON with an X-Inertia header, not an HTML error page — check the network tab rather than the Laravel error view. For 409s, the asset version hash is stale; a hard reload or npm run build fixes it.

Storage and permissions. Media uploads fail silently-ish when the storage symlink is missing or the disk permissions are wrong. Confirm the symlink and the configured disk (FILESYSTEM_DISK) before debugging block code.

Extension points worth knowing: custom block/template registration, custom field types, policies/middleware overrides for the admin routes, and config-level locale definitions for multi-language content. These cover most "the CMS doesn't quite do X" requests without forking.

Caveat: the specific command names and config keys above are stable across v1.x but should be verified against the repo's README and config/vilt.php for 1.1.5 — the sparse release notes give no confirmation either way.