| Package Data | |
|---|---|
| Maintainer Username: | spatie |
| Maintainer Contact: | sebastian@spatie.be (Sebastian De Deyne) |
| Package Create Date: | 2018-01-17 |
| Package Last Update: | 2024-04-19 |
| Home Page: | https://sebastiandedeyne.com/posts/2018/server-side-rendering-javascript-from-php |
| Language: | PHP |
| License: | MIT |
| Last Refreshed: | 2024-11-23 03:00:45 |
| Package Statistics | |
|---|---|
| Total Downloads: | 402,864 |
| Monthly Downloads: | 6,388 |
| Daily Downloads: | 202 |
| Total Stars: | 663 |
| Total Watchers: | 19 |
| Total Forks: | 63 |
| Total Open Issues: | 0 |
Making server side rendering a bit less hard in Laravel.
<html>
<head>
<title>My server side rendered app</title>
<script defer src="{{ mix('app-client.js') }}">
</head>
<body>
{!! ssr('js/app-server.js') !!}
</body>
</html>
This package is a Laravel bridge for the spatie/server-side-rendering library. Before getting started, dig through the readme to learn about the underlying concepts and caveats. This readme also assumes you already have some know-how about building server rendered JavaScript apps.
Vue and React example apps are available at spatie/laravel-server-side-rendering-examples if you want to see it in action.
You can install the package via composer:
composer require spatie/laravel-server-side-rendering
The service provider and Ssr alias will be automatically registered.
You can optionally publish the config file if you want to tweak things.
php artisan vendor:publish --provider="Spatie\Ssr\SsrServiceProvider" --tag="config"
First you'll need to pick an engine to execute your scripts. The server-side-rendering library ships with V8 and Node engines. By default, the package is configured to use node, since you probably already have that installed on your system.
Set up the NODE_PATH environment variable in your .env file to get started:
NODE_PATH=/path/to/my/node
You'll also need to ensure that a storage/app/ssr folder exists, or change the ssr.node.temp_path config value to something else.
If you'd rather use the V8 engine, you can skip the previous two steps. You'll need to have the v8js extension installed though.
Besides the above, no configuration's required. If you need to tweak things anyway, the config file is well documented.
You'll need to build two scripts: a server script and a client script. Refer to your frontend-framework-of-choice's documentation on how to build those.
mix.js('resources/assets/js/app-client.js', 'public/js')
.js('resources/assets/js/app-server.js', 'public/js');
The server script should be passed to the ssr function, the client script should be loaded manually. The package assumes you're using Laravel Mix, and will resolve the path for you. You can opt out of this behaviour by setting mix to false in the config file.
{!! ssr('js/app-server.js') !!}
<script src="{{ mix('js/app-client.js') }}">
Your server script should call a dispatch function to send the rendered html back to the view. Here's a quick example of a set of Vue scripts for a server-rendered app. Read the spatie/server-side-rendering readme for a full explanation of how everything's tied together.
// resources/assets/js/app.js
import Vue from 'vue';
import App from './components/App';
export default new Vue({
render: h => h(App),
});
// resources/assets/js/app-client.js
import app from './app';
app.$mount('#app');
// resources/assets/js/app-server.js
import app from './app';
import renderVueComponentToString from 'vue-server-renderer/basic';
renderVueComponentToString(app, (err, html) => {
if (err) {
throw new Error(err);
}
dispatch(html);
});
The package exposes an ssr helper to render your app.
<html>
<head>
<title>My server side rendered app</title>
<script defer src="{{ mix('app-client.js') }}">
</head>
<body>
{!! ssr('js/app-server.js')->render() !!}
</body>
</html>
A facade is available too.
<html>
<head>
<title>My server side rendered app</title>
<script defer src="{{ mix('app-client.js') }}">
</head>
<body>
{!! Ssr::entry('js/app-server.js')->render() !!}
</body>
</html>
Rendering options can be chained after the function or facade call.
<html>
<head>
<title>My server side rendered app</title>
<script defer src="{{ mix('app-client.js') }}">
</head>
<body>
{!! ssr('js/app-server.js')->context('user', $user)->render() !!}
</body>
</html>
Available options are documented at spatie/server-side-rendering.
composer test
Please see CHANGELOG for more information what has changed recently.
Please see CONTRIBUTING for details.
If you discover any security related issues, please email freek@spatie.be instead of using the issue tracker.
You're free to use this package, but if it makes it to your production environment we highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using.
Our address is: Spatie, Samberstraat 69D, 2060 Antwerp, Belgium.
We publish all received postcards on our company website.
Spatie is a webdesign agency based in Antwerp, Belgium. You'll find an overview of all our open source projects on our website.
Does your business depend on our contributions? Reach out and support us on Patreon. All pledges will be dedicated to allocating workforce on maintenance and new awesome stuff.
The MIT License (MIT). Please see License File for more information.