Theme Agency Laravel Package

Getting Started

capell-app/theme-agency is a Capell theme package (Capell is a Laravel-based CMS), so treat it as a presentation layer rather than a standalone library: it ships Blade views, frontend assets, and theme metadata that get picked up by the host Capell application.

Minimal path from zero to something on screen:

1. composer require capell-app/theme-agency in the host Capell project.
2. Register/select the theme in your Capell configuration (theme name typically mirrors the package suffix, e.g. agency).
3. Publish anything the theme exposes (php artisan vendor:publish --tag=theme-agency — check php artisan vendor:publish output for the exact tags, since tags are the first thing that drifts between releases).
4. Build assets. This theme assumes a Vite/asset pipeline; run the host app's build step (npm install && npm run build) before expecting layouts to render correctly.
5. Load a page in the browser and confirm the layout resolves.

Where to look first:

• The package's composer.json for extra providers and Laravel auto-discovery, and for any Capell-specific registration keys.
• resources/views/ for the layout hierarchy — start at the base layout and follow @extends/@section upward.
• The theme's service provider, if present, for view namespaces, asset registration, and Blade component registration.
• config/ inside the package, if any, for overridable knobs.

First use case: install it, select it as the active theme, and render the home page. That single loop exercises autoloading, theme resolution, view namespace, and asset pipeline at once — if all four are correct, the theme is wired properly.

Implementation Patterns

Theme-as-view-provider. The dominant pattern is that the theme owns the view namespace and the host app consumes it. Don't edit vendor files; instead override individual views by publishing or by placing your own copy earlier in the view path. Keep a short list of overridden view paths in the project README, because overrides silently break on theme upgrades.

Layout inheritance for page types. Agency-style themes usually ship a handful of page templates (home, generic content, contact). Extend rather than duplicate: create your project layouts that @extends the theme's base layout and only override the sections you need. This keeps future theme releases cheap to absorb.

Component-level composition. Extract repeated marketing blocks (hero, CTA, testimonial grid, pricing table) into Blade components or anonymous components in the host app, then reference them from theme-overridden views. This is what makes the theme reusable across sites rather than a one-off fork.

Asset pipeline integration. If the theme ships its own vite.config.js and entry points, decide early whether you build assets inside the package or copy sources into the app's pipeline. Copying into the app's pipeline is usually simpler to reason about; building inside the package is cleaner if you maintain multiple Capell sites off the same theme and don't customize heavily.

Multi-site / multi-theme setups. If the host runs more than one theme, keep theme-specific CSS scoped and avoid pushing theme styles into the global app stylesheet. Theme switching should not require rebuilding app-level assets.

Integration tip for CI. Add a smoke test that boots the app and asserts the themed home route returns 200 and contains a theme-specific marker element (a data attribute on the base layout works well). Theme packages break at the view/asset boundary far more often than in PHP logic, and a render test catches it instantly.

Gotchas and Tips

Version and changelog opacity. The v1.0.50 release notes consist only of a compare link (v1.0.45...v1.0.50), with no described features, fixes, or breaking changes. Treat the intervening five releases as uncharacterized: before upgrading in production, read the commit log at that URL yourself and diff resources/views/ and any published assets between the two tags. Patch-version numbering on a theme package is not a guarantee that markup and CSS are untouched.

View overrides are the main upgrade hazard. Published views snapshot the theme at publish time. After upgrading, re-diff your overridden files against the new vendor originals; a changed variable name or a renamed section will fail silently at render time (blank block) rather than throwing.

Asset cache busting. If styles vanish after an upgrade, the usual cause is a stale manifest or a cached compiled asset, not a broken theme. Clear the app cache and rebuild assets before debugging the package.

Publish tags are unstable across releases. Always run php artisan vendor:publish without arguments first to list live tags rather than copying a tag name from older documentation or a blog post.

Config caching. Theme registration frequently reads from config. If the theme isn't detected after install, php artisan config:clear resolves a surprising share of these cases in cached environments.

Extension points to prefer. Prefer (in order): config values → published views → published assets → Blade components in the host app. Avoid subclassing theme PHP classes; that is the least stable surface and the most likely to break between minor releases.

Debugging a blank page. Work outward: does the route resolve (check php artisan route:list)? Does the view namespace resolve (try view()->exists('theme::layout') in tinker)? Do assets exist in the manifest? That ordering isolates the failure layer in under a minute.

Pin the version once stable. Given the sparse release notes, pin to a specific tag in composer.json and upgrade deliberately, reading the compare diff as part of the upgrade ticket.