use Lame\JSRunner\Renderer;
use Lame\JSRunner\V8Engine as V8;
$engine = new V8();
$renderer = new Renderer($engine);
echo $renderer
->entry(__DIR__.'/../../public/js/app-server.js')
->render();
// <div>My server rendered app!</div>
- Works with any JavaScript framework that allows for server side rendering
- Runs with or without the V8Js PHP extension
- Requires minimal configuration This readme assumes you already have some know-how about building server rendered JavaScript apps.
- Projects that want to call JavaScript from PHP seamlessly.
- Bilingual(PHP and JS/TS) projects that want to render their JS/TS on the server side.
You can install the package via composer:
composer require lanre/jsrunner
An engine executes a JS script on the server. This library ships with three engines: V8Engine
which wraps some V8Js
calls, so you'll need to install a PHP extension for this one,
BunEngine
and NodeEngine
which build a bun/node script (respectively) at runtime and executes it in a new process. An engine can run a script, or an array of multiple scripts.
V8Engine
is a lightweight wrapper around the V8Js
class. You'll need to install the v8js extension to use this engine.
BunEngine
and NodeEngine
write a temporary file with the necessary scripts to render your app, and executes it
in the appropriate environment. You'll need to have node.js (for NodeEngine
) or bun (for BunEngine
) installed to use this engine.
You can chain any amount of options before rendering the app to control how everything's going to be displayed.
echo $renderer
->enableIf($user->isAuthenticated())
->context('user', $user)
->entry(__DIR__.'/../../public/js/app-server.js')
->render();
Enables server side rendering. This is the default state.
Disables server side rendering. When disabled, the client script and the fallback html will be rendered instead.
Conditionally enables server side rendering.
When debug is enabled, JavaScript errors will cause a php exception to throw. Without debug mode, the client script and the fallback html will be rendered instead so the app can be rendered from a clean slate.
The path to your server script. The contents of this script will be run in the engine.
Context is passed to the server script in the context
variable. This is useful for hydrating your application's state. Context can contain anything that json-serializable.
echo $renderer
->entry(__DIR__.'/../../public/js/app-server.js')
->context('user', ['name' => 'Sebastian'])
->render();
// app-server.js
store.user = context.user // { name: 'Sebastian' }
// Render the app...
Context can be passed as key & value parameters, or as an array.
$renderer->context('user', ['name' => 'Sebastian']);
$renderer->context(['user' => ['name' => 'Sebastian']]);
Env variables are placed in process.env
when the server script is executed. Env variables must be primitive values like numbers, strings or booleans.
$renderer->env('NODE_ENV', 'production');
$renderer->env(['NODE_ENV' => 'production']);
Sets the fallback html for when server side rendering fails or is disabled. You can use this to render a container for the client script to render the fresh app in.
$renderer->fallback('<div id="app"></div>');
Add a callback to transform the entry when it gets resolved. It's useful to do this when creating the renderer so you don't have to deal with complex paths in your views.
echo $renderer
->resolveEntryWith(function (string $entry): string {
return __DIR__."/../../public/js/{$entry}-server.js";
})
->entry('app')
->render();
composer test
Please see CHANGELOG for more information what has changed recently.
Please see CONTRIBUTING for details.
- Lanre Waju for creating this package
- Sebastian De Deyne for spatie/server-side-rendering which this package is based on
- All Contributors
The MIT License (MIT). Please see License File for more information.