@ivanlog/gs-server

Server rendering runtime and native Node host for GS 2.0 applications.

Application states, templates and shared services continue to use @ivanlog/gs. Only the final server application and server entrypoint import this package.

The configured shell should contain one <main gs-app></main> mounting root shared with Browser App. SSR replaces this root's children with the current layout and page.

import * as gs from "@ivanlog/gs";
import { AppServer, serve } from "@ivanlog/gs-server";

class ServerApp extends AppServer {
    protected initializeCore(): void {
        gs.StateGS.Configure(states => {
            // Register the same universal route set as Browser App.
        });
    }

    protected async startCore(): Promise<void> {
        // Configure DI and register layouts through this.gui.
    }

    protected resolveLanguage(request: Request): string {
        // Parse application negotiation and return one code, not the complete header.
        return request.headers.get("accept-language")?.split(",", 1)[0]?.split(";", 1)[0] || "en";
    }
}

await serve(new ServerApp(), {
    shell: "./public/index.html",
    assets: "./public",
    host: "127.0.0.1",
    port: 3000,
    publicOrigin: "https://example.com"
});

Set publicOrigin in production when nginx or another reverse proxy terminates HTTPS. GS uses this trusted origin for Request.url, default canonical links, same-origin redirects and SSR cache keys instead of inferring the public scheme and host from the internal Node connection. It must contain only an absolute HTTP(S) origin, for example https://example.com; omit it for a direct local server.

@ivanlog/gs-server requires Node 18 or newer and a matching @ivanlog/gs peer version. It performs anonymous SSR only; authenticated application states remain browser SPA routes. The native host sends a one-year immutable cache header for generated template/CSS fingerprints and versioned browser modules such as gs.2.0.4.min.js and app.1.2.3.min.js. They are served from the configured asset root like every other file under htdocs; no dedicated GS route is required. Every static file advertises Accept-Ranges: bytes. The host supports one bytes range in explicit, open-ended and suffix forms (for example bytes=0-1023, bytes=1024- and bytes=-1024) and streams a successful response as 206 Partial Content. Malformed, unsatisfiable and multiple ranges return 416 Range Not Satisfiable; multipart ranges are intentionally not supported. HEAD follows the same status and header rules without sending a body. Language resolution runs before state, page and layout construction. The selected language is written to the HTML and response headers and forms part of the anonymous SSR cache key.