Server Side Rendering Laravel Package

Getting Started

Start by installing the package via Composer:

composer require spatie/server-side-rendering

Then publish the config file:

php artisan vendor:publish --tag="server-side-rendering-config"

The default config (config/ssr.php) points to storage/app/ssr/index.js as the entry point. Create that file and implement a basic renderer (e.g., using React or Vue). For example:

// storage/app/ssr/index.js
const Vue = require('vue');
const app = new Vue({
  render: h => h({ template: '<div>Hello, {{ name }}!</div>', props: ['name'] }),
  props: ['name'],
});
module.exports = (context) => app.$mount().toString();

In a Laravel controller or view, render like:

use Spatie\Ssr\Facades\Ssr;

return view('welcome', [
    'html' => Ssr::render('index.js', ['name' => 'World']),
]);

Finally, ensure Node.js is installed and accessible in your environment—this package executes the JS file via CLI.

Implementation Patterns

• Renderer abstraction: Encapsulate rendering in a reusable class or service:

  class VueRenderer
  {
      public static function render(string $component, array $props = []): string
      {
          return Ssr::render('index.js', [
              'component' => $component,
              'props' => $props,
          ]);
      }
  }
  

• Caching: Cache SSR output for low-traffic, infrequently changing pages:

  $cacheKey = "ssr:{$component}:" . md5(serialize($props));
  $html = Cache::remember($cacheKey, now()->addDay(), fn() => Ssr::render(...));
  

• Blade integration: Create a @ssr directive or helper:

  // In AppServiceProvider::boot()
  Blade::directive('ssr', fn ($expression) => "<?= \Spatie\Ssr\Facades\Ssr::render({$expression}) ?>");
  

• Dev vs Prod separation: In config/ssr.php, use environment-specific settings (e.g., execCommand() vs http://ssr-container:3000/render) to support Docker or remote rendering in production.

Gotchas and Tips

• Error handling: SSR failures (Node not installed, script crash) throw Spatie\Ssr\Exceptions\RendererException. Wrap calls in try/catch, and fallback to client-side hydration (v-cloak) or static fallback HTML.
• Props serialization: Avoid passing closures, resources, or objects with deep circular references—serialize to JSON before sending (e.g., json_encode($data) in JS context).
• Path issues: Use absolute paths in execCommand() (e.g., php artisan path:resolve(storage_path('app/ssr/index.js'))) to avoid environment-specific bugs.
• Performance: Node startup is slow. For high-traffic sites, run SSR as a long-lived Node process (e.g., via spatie/server-side-rendering’s HTTP renderer or your own Fastify/Express service) and call it over HTTP.
• Testing: Mock Ssr::render() in unit tests; use feature tests with real Node to validate your renderer script end-to-end.
• Debugging: Temporarily set execCommand to ['node', '--inspect-brk', $script] and attach your IDE debugger, or log $command in the Ssr facade to inspect the exact CLI invocation.