Styleguide Laravel Package

Getting Started

Minimal Setup

1. Installation Run composer require in10/styleguide in your Laravel project root. Publish the package assets (if needed) with:

   php artisan vendor:publish --provider="IN10\Styleguide\StyleguideServiceProvider"
   

2. First Use Case Place your Blade template files (e.g., _variables.scss, _buttons.blade.php) in: /resources/views/styleguide/ Access the styleguide via /styleguide in your browser.

3. Where to Look First

   • Check the /resources/views/styleguide/ directory for template organization.
   • Review the package’s routes/web.php (auto-loaded) for the /styleguide route.
   • Inspect the default styleguide.blade.php in the package’s views for structure.

Implementation Patterns

Workflow Integration

1. Component-Based Development

   • Use the styleguide to document reusable Blade components (e.g., components/buttons.blade.php).
   • Example structure:

     /resources/views/styleguide/
     ├── _variables.scss       # SCSS variables
     ├── components/
     │   ├── buttons.blade.php  # Button variants
     │   └── cards.blade.php    # Card layouts
     └── pages/
         └── forms.blade.php    # Form examples
     

2. Live Reloading

   • Pair with Laravel Mix or Vite for hot-reloading during development.
   • Example webpack.mix.js:

     mix.js('resources/js/app.js', 'public/js')
        .sass('resources/scss/app.scss', 'public/css')
        .options({ processCssUrls: false }); // Critical for styleguide assets
     

3. Versioned Styleguides

   • Use subdirectories (e.g., /styleguide/v1/, /styleguide/v2/) for major updates.
   • Override the default route in routes/web.php:

     Route::get('/styleguide/{version?}', [StyleguideController::class, 'show'])
         ->where('version', 'v[0-9]+');
     

4. API Documentation

   • Embed API responses in Blade templates using @include('styleguide.api.example').
   • Fetch data dynamically in the styleguide controller:

     public function show($version = null) {
         return view('styleguide.index', [
             'apiExamples' => ApiService::fetchExamples($version),
         ]);
     }
     

Gotchas and Tips

Pitfalls

1. Asset Loading Conflicts

   • Issue: Styleguide CSS/JS may conflict with app assets if not namespaced.
   • Fix: Use unique class prefixes (e.g., .styleguide-*) or isolate assets:

     // In StyleguideServiceProvider.php
     public function boot() {
         $this->loadViewsFrom(__DIR__.'/views', 'styleguide');
     }
     

2. Route Caching

   • Issue: Routes may not update after changes if cached.
   • Fix: Clear routes after publishing:

     php artisan route:clear
     

3. Blade Component Isolation

   • Issue: Components may break if they rely on global JS/CSS.
   • Fix: Use @once or @stack directives to isolate dependencies:

     @once
         @push('styleguide-scripts')
             <script src="/js/styleguide-utils.js"></script>
         @endpush
     @endonce
     

Debugging Tips

1. Check the View Path

   • Verify templates are in /resources/views/styleguide/ (case-sensitive on some systems).
   • Debug with:

     dd(view()->exists('styleguide.index')); // Should return true
     

2. Asset Debugging

   • Use Laravel Mix’s mix.version() to debug asset paths:

     mix.setPublicPath('public/styleguide-assets');
     

3. Route Debugging

   • Inspect registered routes:

     php artisan route:list | grep styleguide
     

Extension Points

1. Custom Controllers

   • Override the default controller by binding it in AppServiceProvider:

     $this->app->bind(
         StyleguideController::class,
         CustomStyleguideController::class
     );
     

2. Dynamic Content

   • Extend the styleguide with dynamic data via middleware:

     public function handle($request, Closure $next) {
         if ($request->is('styleguide*')) {
             $request->merge(['styleguide_data' => collect(['key' => 'value'])]);
         }
         return $next($request);
     }
     

3. Theming Support

   • Use Blade @stack to inject theme-specific assets:

     @stack('styleguide-themes::css')
     @stack('styleguide-themes::js')