Lara Pro Base Theme Laravel Package

Getting Started

This is a base theme for Lara CMS 10, not a standalone UI kit. The single most important thing to understand before installing: it expects the Lara CMS core (its Page/content models, admin conventions, and service providers) to already be in place. Dropping it into a vanilla Laravel app gets you Blade files that reference models and helpers you don't have.

1. Read the off-repo docs first. The README is essentially a stub pointing at https://docs.laracms.nl/. That developer guide is the real documentation; this repository is source only. Budget half a day there before writing code.

2. Confirm stack alignment. The release history tells you what the theme targets, and it moves in lockstep with the CMS core:

   Theme version	Notable stack change
   10.6.0	Laravel 13
   10.5.0	Filament 5 + Livewire 4
   10.3.0	Bootstrap → Tailwind

   Match the theme's major/minor to your Lara CMS core version, and pin it exactly.

3. Look at, in order: composer.json (namespaces, require constraints, autoloaded service provider), the theme's service provider (what it registers, what's publishable), then the Blade layout hierarchy (master/app layout and its partials). That's your real API surface — there are no facades or documented PHP contracts.

4. First use case: one vertical slice. Render a single CMS page through the theme's layout, then change exactly one thing — a nav item, the logo, or the footer — using the intended override mechanism. If you can't do that without editing files inside vendor/, stop and re-read the view-namespace setup before going further.

Implementation Patterns

Override, never fork-in-place. Publish the theme's views into resources/views/vendor/{theme-namespace}/ and copy only the files you need to change. Laravel's view finder prefers the app path, so overrides win while the package stays upgradeable. Same rule for assets: don't edit published CSS/JS — import the theme's stylesheet from your own Vite entry and layer overrides on top.

Compose the layout, don't copy it. In your app views, @extends the theme's master layout and fill its @yield/@stack sections. Everything site-wide — analytics, extra meta, nav additions, footer legal links — belongs in a section override, not in a duplicated master.blade.php. Duplicating the master is the fastest way to make every future theme release a merge conflict.

Feed CMS data with view composers. Nav menus, footer content, site settings, and featured items should arrive via view composers bound in your service provider, not by querying inside Blade. This keeps the theme partials dumb and lets you swap data sources (a settings table, a cache, an external feed) without touching markup.

Map content blocks 1:1 to Blade partials. Put section partials in one directory (resources/views/sections/) and resolve them from the CMS block type. Editors then get a predictable catalogue, and adding a section is one partial plus one registration — not a controller change.

Build interactions as Livewire components, not page-specific JS. Since 10.5.0 the ecosystem is Livewire 4 + Filament 5. Front-end interactivity (search, filters, forms, pagination) should be a Livewire component dropped into a theme slot; admin-side configuration should be a Filament resource. Mixing in hand-rolled fetch calls fights the grain of the stack and will break on the next major.

Tailwind config is your design-token layer. Post-10.3.0, extend the theme's tailwind.config.js (colors, spacing, fonts) rather than adding a second preprocessor or a parallel CSS framework. For per-brand theming, expose the palette as CSS custom properties resolved at runtime and reference those from Tailwind.

Daily upgrade loop. Work on a branch: bump the exact version → composer update → run the app → diff the published views against the vendor source (git diff --no-index) to see what markup changed upstream → smoke-test → merge. Because this is the base theme, upstream view changes propagate into every site you've built on it, so this check is not optional.

Gotchas and Tips

• It's a theme, not a library. There is no documented PHP API, no facade, no events list in the README. Your integration surface is Blade views plus Lara CMS conventions. If the docs site doesn't answer a question, reading the theme source is the only reliable path.
• Version drift fails silently. A theme built for Laravel 13 / Filament 5 / Livewire 4 on a mismatched core doesn't throw a clean "unsupported version" error — you get a missing Blade component, an undefined Livewire component, or a blank admin panel. Pin exactly ("10.6.*") and upgrade core and theme together.
• The Bootstrap → Tailwind cliff (10.3.0). Any snippet, internal wiki page, or StackOverflow answer written before that release uses row, col-md-*, btn-*, card classes. After 10.3.0 those render as nothing — no error, just unstyled markup. Grep your overrides for Bootstrap class names whenever porting old code.
• The Livewire 3 → 4 jump (10.5.0). Older component patterns and directive syntax may not carry over. Check the version of any example you copy. You may also need separate Vite entries for front-end theme assets and admin (Filament) assets.
• Changelogs won't help you. Nearly every release note is literally "Several improvements." Don't plan upgrades from the notes; diff the tags on GitHub, or just diff the published views locally and let the smoke tests catch the rest.
• "My override isn't applying" is almost always a namespace/cache issue. Confirm you're writing to the exact vendor view path the theme registers, then php artisan view:clear. Use the view finder to print the resolved path of the view you think you're editing rather than guessing.
• Config and asset caching on deploy. If the theme reads config at boot, config:cache will freeze values from build time — always clear caches after deploy. If published assets aren't hashed through the Vite manifest, users will see stale CSS after a theme update; serve theme assets through Vite.
• Zero stars, zero dependents, vendor-maintained. Expect no community answers and no third-party tutorials. Treat it as an internal dependency: keep a fork in your own VCS if you need patch stability, and maintain a written list of your local patches so upstream rebases stay cheap.
• Prefer extension points in this order: view composers → Blade components → Livewire slots → middleware → view overrides → forking. Reaching for a fork early costs you every future upstream fix.
• Write three smoke tests and never remove them: home page returns 200, a CMS page renders its content, admin login works. Given the opaque release notes, these tests are your only real upgrade safety net.