Laravel Server Side Rendering Laravel Package

Getting Started

Install the package via Composer, publish the optional config file, and ensure your environment supports your chosen engine (Node.js or V8js). Start by rendering a minimal SSR-enabled page: create resources/js/app-server.js that renders your component and calls dispatch(html), then use {!! ssr('js/app-server.js') !!} in your Blade layout. For newcomers, review the official examples repo and check the ssr() helper’s signature—it’s the primary entry point you’ll interact with daily.

Implementation Patterns

Most day-to-day usage revolves around replacing client-side mount points with ssr() calls in Blade templates. Common patterns include:

• Using ssr()->context('key', $value) to pass server-side variables (e.g., auth user, config) into the JS context
• Bundling dual entry points via Laravel Mix: mix.js('client.js', 'dist').js('server.js', 'dist')
• Leveraging the Ssr facade for more complex rendering chains (e.g., conditional rendering with ->renderWhen())
• Wrapping SSR in Blade @section blocks to maintain layout consistency across SSR and non-SSR pages

Integrate with Laravel Octane by enabling it—this package auto-detects and uses Swoole/RoadRunner workers for persistent JS runtimes—avoiding cold-start latency on repeated requests.

Gotchas and Tips

• Engine pitfalls: Node engine is easier to set up, but requires explicit NODE_PATH config and a writable storage/app/ssr directory. V8js is faster but finicky—ensure phpinfo() shows v8js and verify thread-safety in production.
• Error handling: SSR failures won’t throw in production unless explicitly configured; wrap critical renders in try/catch via Ssr::tryRender() (if available) or fallback to client-only rendering with Blade conditionals.
• Asset caching: When using mix() resolution, always re-run npm run dev or npm run build after changing SSR bundles—stale Mix manifest will silently fail.
• Testing: Use php artisan config:clear after toggling engine configs—changes to ssr.php aren’t hot-reloaded in development.
• Performance: For high-traffic apps, consider disabling SSR in APP_DEBUG=true environments or using ssr()->disabled() in non-critical pages to preserve server resources.