Sidecar Shiki Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/sidecar-shiki
   

   Ensure your Laravel app has Sidecar configured (this package extends Sidecar’s functionality).

2. First Use Case: Highlight a code snippet in a Blade template:

   use Spatie\SidecarShiki\Facades\SidecarShiki;
   
   $highlighted = SidecarShiki::highlight(
       code: 'function hello() { return "world"; }',
       language: 'javascript'
   );
   

   Render in Blade:

   <div>{{ $highlighted }}</div>
   

3. Key Files:

   • config/sidecar-shiki.php (default config, minimal setup required).
   • app/Providers/SidecarShikiServiceProvider.php (auto-registered; no manual binding needed).

Implementation Patterns

Core Workflows

1. Dynamic Highlighting in Controllers:

   public function showCodeExample()
   {
       $code = file_get_contents('path/to/file.php');
       $highlighted = SidecarShiki::highlight($code, 'php');
   
       return view('examples.show', compact('highlighted'));
   }
   

2. Caching Highlighted Output: Use Laravel’s cache to avoid redundant Lambda calls:

   $cacheKey = "shiki_{$language}_{md5($code)}";
   $highlighted = Cache::remember($cacheKey, now()->addHours(1), function() use ($code, $language) {
       return SidecarShiki::highlight($code, $language);
   });
   

3. Integration with Markdown Parsers: Extend a Markdown parser (e.g., spatie/laravel-markdown) to auto-highlight code blocks:

   // In a custom Markdown renderer
   $highlighted = SidecarShiki::highlight($blockContent, $language);
   return "<pre><code class=\"language-{$language}\">{$highlighted}</code></pre>";
   

4. Sidecar Configuration: Ensure your sidecar.php config includes Shiki:

   'services' => [
       // ...
       'shiki' => [
           'handler' => Spatie\SidecarShiki\SidecarShikiHandler::class,
       ],
   ],
   

Gotchas and Tips

Pitfalls

1. Lambda Timeouts:

   • Shiki processing may hit AWS Lambda’s 15-minute timeout for large files. Split code into chunks or use Sidecar’s timeout config:

     'shiki' => [
         'timeout' => 30, // seconds
     ],
     

2. Language Detection:

   • Shiki requires explicit language specification. Use spatie/array-to-xml or regex to guess languages if omitted:

     $language = preg_match('/^\s*<\?php/', $code) ? 'php' : 'text';
     

3. HTML/JS Injection:

   • Escaped output may break if Shiki injects raw HTML. Sanitize with Laravel’s e() or a whitelist:

     {!! e($highlighted) !!}
     

Debugging

• Logs: Enable Sidecar’s debug mode in config/sidecar.php:

  'debug' => env('SIDECAR_DEBUG', false),
  

• Payload Inspection: Dump the raw request/response via Sidecar’s Sidecar::call():

  $response = Sidecar::call('shiki', [
      'code' => $code,
      'language' => $language,
  ], debug: true);
  

Extension Points

1. Custom Themes: Override Shiki’s default theme by extending the handler:

   // app/Providers/SidecarShikiServiceProvider.php
   public function register()
   {
       $this->app->extend(SidecarShikiHandler::class, function ($handler) {
           $handler->setTheme('github-dark');
           return $handler;
       });
   }
   

2. Pre/Post-Processing: Hook into Sidecar’s pipeline to transform input/output:

   Sidecar::extend('shiki', function ($payload, $next) {
       $payload['code'] = str_replace("\r\n", "\n", $payload['code']);
       return $next($payload);
   });
   

3. Fallback for Offline: Use a local Shiki instance as a fallback (requires Node.js):

   if (!app()->environment('production')) {
       $highlighted = SidecarShiki::highlight($code, $language, useLocalFallback: true);
   }