Laravel Shadebridge Laravel Package

Getting Started

Shadebridge brings shadcn/Tweakcn theming into a Laravel app: you import a theme JSON, it produces the CSS variables/metadata your frontend consumes, and you can switch or reset themes via Artisan. This release is a rename and repackage — the Composer name is yukazakiri/laravel-shadebridge and the PHP namespace is Yukazakiri\Shadebridge. If you had a prior integration, this is the first thing to change.

composer require yukazakiri/laravel-shadebridge
php artisan vendor:publish --tag=shadebridge-config   # inspect paths/defaults first
php artisan theme:import path/to/theme.json

Where to look first:

1. The published config — theme storage path, generated CSS location, and the default theme name.
2. The shared importer — theme:add and theme:import now use the same importer, so reading that one class explains both commands.
3. Your app's CSS entrypoint — make sure the generated CSS file is actually imported by your Tailwind/frontend build.

First real use case: take a shadcn theme JSON (e.g. exported from Tweakcn), run theme:import, confirm the CSS variables appear in the generated file, then npm run build and eyeball the result.

Implementation Patterns

Import vs. add. theme:import is for a JSON file you point at; theme:add is the convenience path for adding a theme by reference. They share the importer, so validation and output are identical — pick based on whether the theme already exists locally or needs fetching.

php artisan theme:import ./themes/ocean.json
php artisan theme:add ocean

Forced refresh. The importer forces CSS and metadata regeneration. That makes it safe to re-run as a repair step (theme:import again fixes a hand-mangled theme), but it means you should not treat the generated files as source of truth.

System defaults at build time. theme:default sets the fallback theme and cleans up removed themes. Use it in deploy/build scripts so the app always has a valid theme even before any runtime selection happens:

# deploy script
php artisan theme:import ./themes/ocean.json
php artisan theme:default ocean
npm ci && npm run build

Frontend integration (React/Vue). The package ships a pre-hydration initializer plus a stale-selection fallback. Register the initializer in your entrypoint before mounting/hydrating so the first paint already has the right CSS variables, and let the fallback handle the case where a stored theme selection no longer exists after a rename/removal:

import { initShadebridge } from '.../shadebridge'; // package-provided initializer
initShadebridge();          // runs pre-hydration, resolves stale selections
createRoot(el).render(<App />);

Removal. Removing a theme is now a clean operation; follow it with theme:default so nothing references the gone theme.

php artisan theme:remove ocean
php artisan theme:default ocean-blue

CI. Mirror the package's own matrix expectations: PHP 8.2–8.4, Laravel 12–13. Add a step that imports the theme and rebuilds assets so a broken theme JSON fails the build, not production.

Gotchas and Tips

• Breaking rename. Existing integrations must update both composer.json (yukazakiri/laravel-shadebridge) and every use statement (Yukazakiri\Shadebridge\...). Do a project-wide search for the old namespace before bumping; a stale import shows up as an unhelpful "class not found" at runtime.
• Assets don't rebuild themselves. Theme changes only take effect after npm run build (or your dev watcher restarts). If nothing looks different, this is almost always the cause.
• TLS verification is on. Imports that fetch remote themes will fail hard against self-signed certs, corporate MITM proxies, or an outdated CA bundle. On CI, ensure ca-certificates is current rather than disabling verification.
• Don't hand-edit generated CSS. Because refresh is forced on every import, manual tweaks to the generated file are silently clobbered. Put custom overrides in your own stylesheet layered after the generated import.
• Ordering matters for theme:default. It writes build-time system defaults and cleans removals — run it after imports, before the asset build. Running it before an import can leave the default pointing at a theme that hasn't been written yet.
• Stale selections are handled, not impossible. The React/Vue fallback catches users whose stored theme was deleted, but you should still test a "delete the active theme" scenario end-to-end to confirm the fallback lands on the intended default.
• Pre-hydration initializer and SSR. It runs before hydration on the client; if you server-render, make sure the server-side markup doesn't assume a specific theme or you'll get a hydration mismatch flash.
• Debugging checklist: (1) did the import command exit cleanly and print validation errors, (2) does the generated CSS file contain your variables, (3) does your CSS entrypoint import it, (4) did you rebuild, (5) is the frontend initializer running before mount.
• Validation is your friend. The importer now validates Tweakcn/shadcn JSON before writing anything. A malformed export fails at import time with a clear error instead of producing half a theme file — trust it rather than patching the JSON by hand.