ssr-rs

The integration between Solid.js, Vite, and the ssr-rs Rust library follows this lifecycle:

1. Client Build: A standard Vite build generates the client-side bundle for browser execution.
2. Server Build: Running build:rust-ssr creates a specialized server bundle that exports a renderToString function.
3. Rust Integration: The Rust server (implemented in server.rs) loads this server bundle and invokes the renderToString function to generate the initial HTML.
4. Hydration: Once the HTML is delivered to the browser, the client-side JavaScript (from src/main.tsx) executes to hydrate the application, making it interactive.

Key Files in this Architecture

• src/server-entry.tsx: The server-side entry point that exports the required render function.
• src/main.tsx: The client-side entry point responsible for hydration.
• server.rs: The Rust server implementation that serves the rendered HTML.
• vite.config.ts: The Vite configuration containing specific SSR settings.

The entryPoint argument in Ssr::new tells the engine where to find the rendering logic within your bundled JavaScript. It can be:

• An empty string (""): Use this if your bundle is an IIFE (Immediately Invoked Function Expression) that returns the required object, or if the bundle is just a plain object.
• A variable name: Use the name of the variable that holds the object containing your rendering functions (e.g., "SSR").

Examples of entryPoint mapping:

IIFE (entryPoint = "")

(() => ({ renderToStringFn: (props) => "<html></html>" }))()

Plain Object (entryPoint = "")

({renderToStringFn: (props) => "<html></html{}"})

IIFE Variable (entryPoint = "SSR")

var SSR = (() => ({renderToStringFn: (props) => "<html></html>"}))()

Variable (entryPoint = "SSR")

var SSR = {renderToStringFn: (props) => "<html></html>"};

The examples/ directory contains various implementations of Server-Side Rendering (SSR) using different frontend bundlers and backend frameworks. Use these as templates for your own projects.

React Implementations

• webpack-react: The most comprehensive React example. It demonstrates:
  • Server-side props handling
  • React hydration
  • Asset generation
• vite-react: A simplified example showcasing a base bundler configuration using Vite.
• rspack-react-ts-starter: A simplified example showcasing a base bundler configuration using Rspack.

Note: If you are using Vite or Rspack and need advanced features like hydration or server-side props, you can port them from the webpack-react example.

Rust Backend Implementations

At the root of the examples folder, you can find simple configurations demonstrating how to integrate SSR with common Rust backend frameworks.

For production applications, it is recommended to enable type-aware linting to improve code quality. To do this, follow these steps:

1. Update parserOptions: Configure the top-level parserOptions in your ESLint configuration to include your tsconfig files.
2. Update TypeScript Plugins: Replace plugin:@typescript-eslint/recommended with either plugin:@typescript-eslint/recommended-type-checked or plugin:@typescript-eslint/strict-type-checked.
3. Add Stylistic Rules (Optional): Add plugin:@typescript-eslint/stylistic-type-checked.
4. Add React Plugin: Install eslint-plugin-react and add plugin:react/recommended and plugin:react/jsx-runtime to your extends list.

export default {
  // other rules...
  parserOptions: {
    ecmaVersion: 'latest',
    sourceType: 'module',
    project: ['./tsconfig.json', './tsconfig.node.json'],
    tsconfigRootDir: __dirname,
  },
}

Because the underlying rusty_v8 engine does not yet support the V8 Locker API, the Ssr struct cannot be safely shared across threads. To use ssr_rs in a multi-threaded web server like actix-web, you should use thread_local! to ensure each thread has its own instance of the SSR engine.

Implementation Pattern

1. Initialize the platform with Ssr::create_platform().
2. Define a thread_local! block containing a RefCell<Ssr>.
3. Inside your request handler, use SSR.with(|ssr| ...) to access and borrow the engine for rendering.

use actix_web::{get, http::StatusCode, App, HttpResponse, HttpServer};
use std::cell::RefCell;
use std::fs::read_to_string;

use ssr_rs::Ssr;

thread_local! {
    static SSR: RefCell<Ssr<'static, 'static>> = RefCell::new(
            Ssr::from(
                read_to_string("./client/dist/ssr/index.js").unwrap(),
                "SSR"
                ).unwrap()
            )
}

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    Ssr::create_platform();

    HttpServer::new(|| {
        App::new()
            .service(index)
    })
    .bind("127.0.0.1:8080")?
    .run()
    .await
}

#[get("/")]
async fn index() -> HttpResponse {
    let result = SSR.with(|ssr| ssr.borrow_mut().render_to_string(None).unwrap());

    HttpResponse::build(StatusCode::OK)
        .content_type("text/html; charset=utf-8")
        .body(result)
}