Larecipe Dark Theme Laravel Package

Getting Started

This is a thin, archived (last release Oct 2020) add-on that layers a dark-mode stylesheet and toggle onto LaRecipe. Treat it as a reference implementation rather than a maintained dependency—pin the exact version and expect to vendor/fork it.

Minimal steps:

1. Install LaRecipe first and confirm config/larecipe.php is published and docs render at the configured route (default /docs). The dark theme has nothing to theme until LaRecipe is working.
2. composer require binarytorch/larecipe-dark-theme (pin the 2020 release explicitly; there is no newer constraint solving for modern Laravel).
3. Publish the package assets. The likely tag is larecipe-dark-theme or public—run php artisan vendor:publish --provider="BinaryTorch\LaRecipeDarkTheme\LaRecipeDarkThemeServiceProvider" and inspect config/larecipe.php and public/vendor/larecipe after it runs.
4. Look first at config/larecipe.php (assets.css / assets.js arrays and the theme block). Most dark-theme packages of this era hook in by appending a stylesheet/script to those arrays rather than overriding views.
5. First use case: a toggle in the docs navbar that flips a data-theme="dark" attribute (or a dark class on <body>) and persists to localStorage. Verify by loading /docs, toggling, and reloading—state should survive navigation between doc pages.

If publishing does nothing, open the provider's boot()/register() directly; the integration surface is small enough to reimplement in ~30 lines if needed.

Implementation Patterns

Asset-array registration (most likely mechanism). Rather than a full view override, add the published CSS/JS to LaRecipe's config:

'assets' => [
    'js'  => ['/vendor/larecipe-dark-theme/dark-theme.js'],
    'css' => ['/vendor/larecipe-dark-theme/dark-theme.css'],
],

This avoids forking LaRecipe's Blade views and survives minor LaRecipe upgrades better than template overrides.

Toggle persistence via localStorage. The day-to-day expectation is that a user's dark-mode choice follows them across doc pages and reloads. Read localStorage in an inline script before first paint (in <head>) to avoid a light flash, then have the toggle handler write the value back. Don't rely solely on a class applied after DOMContentLoaded.

Custom CSS variables as the integration seam. Prefer overriding CSS custom properties (--larecipe-bg, --larecipe-text, etc.—check the published stylesheet for the actual variable names) instead of hard-coding colors. This lets you tune a dark palette per project brand without editing the package file, and makes it trivial to swap to your own theming later.

Scope it to docs only. The assets only load under LaRecipe routes, so app-wide dark mode is out of scope. If your product already has a global theme system, bridge it: read your app's theme preference into the LaRecipe toggle so docs match the surrounding UI.

Fork-and-own workflow (recommended over direct dependency). Because the package is archived, the sane pattern is to copy the CSS/JS into resources/ (or a small custom package) and register it via LaRecipe's assets config. You get the same result with zero supply-chain risk and full control over the color palette.

CI/deploy note. Compiled CSS/JS from a 2020 package may not be fingerprinted. If you add it via assets, ensure paths are absolute and versioned (e.g., ?v=...) to sidestep aggressive caching on redeploy.

Gotchas and Tips

• Archived + zero dependents. No Laravel 9/10/11 compatibility work has been done. The provider may declare a service provider or config that assumes old Laravel internals. Test on your exact framework version before relying on it; be ready to inline the two files manually.
• LaRecipe version coupling. The stylesheet targets LaRecipe's DOM/class names as of ~2020. LaRecipe's markup has changed since; a class rename silently breaks styling. After upgrading LaRecipe, smoke-test the toggle and inspect the dark palette for unstyled elements (tables, code blocks, search modal are the usual casualties).
• Asset publish tag guessing. vendor:publish with no tag publishes everything, which can scatter files. Run php artisan vendor:publish --tag=<tag> --force after confirming the tag in the provider—wrong tags appear to "succeed" while doing nothing.
• Cache clearing. Config and view caches mask asset-array changes: php artisan config:clear && php artisan view:clear && php artisan cache:clear. If the toggle vanishes, this is the first thing to rule out.
• FOUC (light flash). Any toggle that runs on DOMContentLoaded will flash white before applying dark styles. Put the localStorage read + class application inline in <head>.
• Config publishing collisions. Publishing this package's config can overwrite your existing config/larecipe.php. Diff before --force, or merge manually.
• Extension point. The cleanest long-term move is to bypass the package: keep LaRecipe's stock theme, add your own docs-dark.css using CSS variables, and a 15-line toggle script in assets.js. You get identical behavior plus maintainability—this is exactly what the "low opportunity" score reflects.
• Debugging checklist: Is the asset 404ing (check the browser network tab and /vendor/ path)? Is the toggle markup present in the rendered navbar (inspect HTML)? Is localStorage denied in private browsing (guard the read/write)? Does a conflicting project stylesheet win on specificity?