Thompson Theme Bundle Laravel Package

Getting Started

Prerequisites. A standard Laravel app (Blade rendering, not API-only/Inertia-only), Composer, and read access to the eactive Bitbucket workspace. Confirm you have a working credential path (SSH deploy key or Bitbucket app password) before you start — the whole integration hinges on it.

1. Register the private repository. The package is not on Packagist, so Composer needs a VCS entry. Either commit auth.json (avoid), or export credentials and use COMPOSER_AUTH:

{
  "repositories": [
    { "type": "vcs", "url": "[email protected]:eactive/integrated-thompson-theme-bundle.git" }
  ]
}

2. Pin before requiring. With no tagged releases advertised, do not let Composer float a branch. Require explicitly and pin a commit:

composer require "integrated/thompson-theme-bundle:dev-main#<commit-sha>"

Then lock it in composer.json with the same SHA so every CI run resolves identically.

3. Read the source before installing further. Open the package's composer.json first — check illuminate/* and php constraints against your lock file. Then open the service provider. You are looking for four things:

• loadViewsFrom(...) — what view namespace does it claim?
• mergeConfigFrom(...) / publishes(...) — what tags exist?
• loadRoutesFrom(...) / middleware — does it ship routes you didn't ask for?
• Asset handling — mix() or vite() calls in its Blade.

4. Publish and inventory (do not --force). Run in dry-run spirit first:

php artisan vendor:publish --provider="Integrated\ThompsonThemeBundle\ThompsonThemeServiceProvider"

Watch the output. Note every file it writes to config/, resources/views/vendor/, and public/. This inventory is your override surface — write it down.

5. First use case. Render one page through the theme without touching the package: create a view in your app that extends the Thompson layout and visit it. Something like:

{{-- resources/views/welcome.blade.php --}}
@extends('thompson::layouts.app')

@section('content')
    <h1>Hello Thompson</h1>
@endsection

If that renders with the theme's chrome (header/footer/assets), integration is working. Everything after that is refinement of overrides.

Implementation Patterns

Override by namespace, not by fork. Laravel resolves resources/views/vendor/{namespace}/... ahead of the package's own views. Publish only the file you need to change, keep it at that path, and let everything else fall through to the package. This is the single most important habit for keeping upgrades predictable.

# Publish just the views tag, then delete everything you don't intend to override.
php artisan vendor:publish --tag=thompson-views

Extend the layout, don't rebuild it. The theme is designed for Blade inheritance. Use @extends for the page skeleton and @section/@yield for content. Use @push('scripts') / @push('styles') for page-specific assets — provided the layout declares the matching @stack. Verify the stack names in the layout once and document them.

Config-driven branding. Publish the config file and treat it as the day-one customization surface for logos, colors, and layout flags. This keeps per-project differences out of Blade and in a single file, which is far easier to review and roll forward.

php artisan vendor:publish --tag=thompson-config

Multi-tenant / per-tenant presentation. Set the relevant config values before rendering (e.g., in a tenant-resolving middleware) and rely on view:cache for compiled Blades:

config([
    'thompson.logo'   => tenant()->logo_url,
    'thompson.accent' => tenant()->brand_color,
]);

Keep tenant-specific overrides in the tenant record, not in per-tenant copied view directories — copied views are the thing this bundle exists to avoid.

Asset pipeline integration. The two branches here matter enormously:

• If the bundle uses @vite / vite(): the package needs its own manifest, or you point it at the host app's public/build. Publish its vite.config assets or add the theme's entry points to your host vite.config.js so a single manifest serves both.
• If the bundle uses mix(): laravel-mix must be installed, and the published mix-manifest.json must resolve. If your host has moved to Vite, this is where integration cost lives — either run Mix alongside Vite for the theme, or rewire the layout to @vite under your own override.

Either way, publish the theme's static assets into public/ and commit them (or build them in a deploy step). Do not gitignore theme assets that come from a package with no build pipeline you control.

Route and nav assumptions. Themes usually assume named routes (home, dashboard, login) and a known menu structure. Grep the published views for route('...') early. If the theme expects route names your app doesn't have, either add aliases in RouteServiceProvider or override the specific partial that renders the nav — do not rename your app's routes.

Testing pattern. Add one feature test per themed entry point that asserts the layout is active:

$this->get('/')->assertOk()->assertSee('thompson-theme', false);

This catches the silent-failure case where the view namespace resolves correctly but a partial override has broken the page.

CI/CD. Wire credentials as an environment variable, never in the repo:

- run: composer install --no-interaction --prefer-dist
  env:
    COMPOSER_AUTH: ${{ secrets.COMPOSER_AUTH }}

Use an SSH deploy key scoped to this one repository with read-only access. Rotate on a documented schedule — expired credentials failing composer install is the most likely production outage from this package.

Gotchas and Tips

vendor:publish is destructive on repeat. Running it again with --force will overwrite your customized overrides. Never --force in a deploy script. If you must republish after an upgrade, diff first:

git diff -- resources/views/vendor/thompson config/thompson.php

View namespace precedence is silent. Blade overrides fail quietly — you get the package's partial rendered instead of yours, with no error. When an override "isn't taking," check, in order: php artisan view:clear, the exact path under resources/views/vendor/{namespace}/, and the namespace string in @extends (it must match loadViewsFrom's first argument exactly).

Config cache bites on upgrade. If config:cache is active in staging/production, changes to the published config/thompson.php do not apply until you re-run php artisan config:cache. Always re-cache after deploying a theme version bump.

Pin the commit, not the branch. dev-main resolves to whatever HEAD is when CI runs — an unreviewed commit can land in production during a routine deploy. Pin the SHA in composer.json, bump deliberately, and record the reason for the bump in the commit message.

Mix vs Vite is the most common breakage. mix() throws if laravel-mix isn't installed; @vite throws ViteManifestNotFoundException if the manifest isn't at public/build/manifest.json. Check which helper the package's layouts use before you commit to upgrading the host's build tool.

View caching and view:cache. php artisan view:cache compiles package views too. If you override a partial in resources/views/vendor/, you must view:clear before the compiled package version is discarded. Warm the cache in your deploy script after any publish step.

Extension points worth knowing:

• Config — safest customization axis, survives upgrades cleanly.
• Partial overrides under resources/views/vendor/{namespace}/partials/ — fine-grained, but each one is a file you now maintain.
• Full layout override — last resort; if you're overriding layouts/app.blade.php wholesale you have effectively forked the theme.

Debugging checklist when a page looks wrong:

1. php artisan view:clear && php artisan config:clear
2. Confirm the namespace in @extends matches the provider's loadViewsFrom argument.
3. php artisan vendor:publish --provider=... again to see which files the package expects to be at the published paths.
4. Check the browser network tab for asset 404s — a 404 on a theme asset is almost always a manifest path or a missing public/ publish.
5. php artisan route:list if nav/menu items point to routes you didn't define.

Avoid the "just copy the views in" temptation. Copying the whole view tree into your app defeats the point of the bundle and guarantees you can never take an upstream fix. If a required change can't be expressed as a single-partial override, raise it upstream — that is the cheapest long-term work.

Asset and font licensing. Before shipping anything client-facing, confirm the theme's fonts, icons, and images are licensed for that use. A theme bundle frequently ships assets whose license doesn't transfer with the code.

Document your overrides. Keep an OVERRIDES.md in your repo listing each published file, why it was overridden, and the package version it was published from. When the next upgrade lands, that file is the difference between a 30-minute rebase and a two-day archaeology session.

Watch the Illuminate constraint. Theme bundles are the classic casualty of Laravel major upgrades. Before starting a Laravel upgrade, check the package's composer.json for the new major and, if it's absent, plan the fork/override path before you bump the framework, not after.