@jslop/node-adapter 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 p-arndt 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# @jslop/node-adapter
+
+A Node HTTP wrapper around a built JSlop SSR `render(url)`. Serves static assets from `dist/client/` and falls through to the SSR entry for everything else.
+
+```bash
+pnpm add @jslop/node-adapter
+```
+
+## Usage
+
+Build your app first (see [`@jslop/vite`](../vite) docs):
+
+```bash
+vite build              # → dist/client/
+vite build --ssr        # → dist/server/entry-server.js
+```
+
+Then drop in a serve script:
+
+```js
+// serve.mjs
+import { createServer } from "@jslop/node-adapter";
+import { render } from "./dist/server/entry-server.js";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const server = createServer({
+  render,
+  clientDir: resolve(here, "dist/client"),
+});
+
+server.listen(Number(process.env.PORT ?? 3000), () => {
+  console.log(`listening on http://localhost:${process.env.PORT ?? 3000}`);
+});
+```
+
+```bash
+node serve.mjs
+```
+
+## API
+
+### `createHandler(opts) → (req, res) => void`
+
+Returns a Node HTTP request handler.
+
+| Option               | Type                                                              | Required | Notes                                                                |
+|----------------------|-------------------------------------------------------------------|----------|----------------------------------------------------------------------|
+| `render`             | `RenderFn`                                                        | yes      | The function exported by `dist/server/entry-server.js`.              |
+| `clientDir`          | `string`                                                          | yes      | Absolute path to the built client dir (typically `dist/client`).     |
+| `title`              | `(url, params) => string`                                         | no       | Forwarded to `render` as `opts.title`.                               |
+| `clientManifestPath` | `string`                                                          | no       | Override path to `.vite/manifest.json`. Defaults to `<clientDir>/.vite/manifest.json`. |
+
+Behavior:
+
+- If the request path has a file extension (`.js`, `.css`, `.png`, ...) and the file exists under `clientDir`, it's served as a static asset.
+- Files under `/assets/` get `cache-control: public, max-age=31536000, immutable` — safe because Vite hashes their filenames.
+- Path traversal is blocked: anything that resolves outside `clientDir` falls through to `render`.
+- All other requests call `render(url, { title, clientManifestPath })`. The result's `status`, `headers`, and `html` are written to the response.
+- Render errors are logged and answered with `500 internal server error`.
+
+### `createServer(opts) → http.Server`
+
+Same options as `createHandler`, plus passes the handler to `http.createServer`. Returns the unstarted server — call `.listen(port)` yourself.
+
+### Types
+
+```ts
+type RenderFn = (
+  url: string,
+  opts?: {
+    appScriptUrl?: string;
+    stylesheets?: string[];
+    title?: (url: string, params: Record<string, string>) => string;
+    clientManifestPath?: string;
+  }
+) => Promise<{
+  status: number;
+  html: string;
+  headers: Record<string, string>;
+}>;
+```
+
+The `RenderFn` shape is intentionally request-agnostic — only a URL string in, a result object out — so Bun / edge / fetch-handler adapters can be written against the same contract.

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import { type IncomingMessage, type ServerResponse, type Server } from "node:http";
+/**
+ * Shape of `render` exported by `virtual:jslop-entry-server`.
+ */
+export type RenderFn = (url: string, opts?: {
+    appScriptUrl?: string;
+    stylesheets?: string[];
+    title?: (url: string, params: Record<string, string>) => string;
+    clientManifestPath?: string;
+}) => Promise<RenderResult>;
+export interface RenderResult {
+    status: number;
+    html: string;
+    headers: Record<string, string>;
+}
+export interface NodeAdapterOptions {
+    /** The bundled `render` function from `dist/server/entry-server.js`. */
+    render: RenderFn;
+    /** Absolute path to the client build dir (typically `dist/client`). */
+    clientDir: string;
+    /** Optional title generator passed through to render(). */
+    title?: (url: string, params: Record<string, string>) => string;
+    /** Override path to `.vite/manifest.json`. Defaults to `<clientDir>/.vite/manifest.json`. */
+    clientManifestPath?: string;
+}
+/**
+ * Build a Node HTTP request handler from a JSlop SSR build.
+ *
+ * Static assets under `clientDir` are served with long cache headers when they
+ * include a hash in the filename (Vite default for `assets/`); other paths
+ * fall through to `render(url)`.
+ */
+export declare function createHandler(opts: NodeAdapterOptions): (req: IncomingMessage, res: ServerResponse) => void;
+/**
+ * Convenience: spin up an http.Server bound to a port.
+ */
+export declare function createServer(opts: NodeAdapterOptions & {
+    port?: number;
+}): Server;

package/dist/index.js

@@ -0,0 +1,100 @@
+import { createServer as createHttpServer } from "node:http";
+import { readFile, stat } from "node:fs/promises";
+import { resolve, join, extname, normalize, sep } from "node:path";
+const MIME = {
+    ".js": "application/javascript; charset=utf-8",
+    ".mjs": "application/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".html": "text/html; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".avif": "image/avif",
+    ".ico": "image/x-icon",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+    ".ttf": "font/ttf",
+    ".otf": "font/otf",
+    ".map": "application/json; charset=utf-8",
+    ".txt": "text/plain; charset=utf-8",
+    ".wasm": "application/wasm",
+};
+/**
+ * Build a Node HTTP request handler from a JSlop SSR build.
+ *
+ * Static assets under `clientDir` are served with long cache headers when they
+ * include a hash in the filename (Vite default for `assets/`); other paths
+ * fall through to `render(url)`.
+ */
+export function createHandler(opts) {
+    const clientDir = resolve(opts.clientDir);
+    const manifestPath = opts.clientManifestPath ?? join(clientDir, ".vite", "manifest.json");
+    return async (req, res) => {
+        try {
+            const url = req.url ?? "/";
+            const pathname = url.split("?")[0] || "/";
+            // Try a static file under clientDir first if the path looks like an
+            // asset (has an extension, isn't a route).
+            const ext = extname(pathname);
+            if (ext) {
+                const served = await tryServeStatic(clientDir, pathname, ext, res);
+                if (served)
+                    return;
+            }
+            const result = await opts.render(url, {
+                title: opts.title,
+                clientManifestPath: manifestPath,
+            });
+            res.statusCode = result.status;
+            for (const [k, v] of Object.entries(result.headers)) {
+                res.setHeader(k, v);
+            }
+            res.end(result.html);
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.error("[@jslop/node-adapter] render error:", err);
+            res.statusCode = 500;
+            res.setHeader("content-type", "text/plain; charset=utf-8");
+            res.end("internal server error");
+        }
+    };
+}
+async function tryServeStatic(clientDir, pathname, ext, res) {
+    // Resolve under clientDir and guard against path traversal.
+    const rel = pathname.replace(/^\/+/, "");
+    const target = normalize(join(clientDir, rel));
+    if (!target.startsWith(clientDir + sep) && target !== clientDir) {
+        return false;
+    }
+    try {
+        const st = await stat(target);
+        if (!st.isFile())
+            return false;
+        const buf = await readFile(target);
+        res.statusCode = 200;
+        res.setHeader("content-type", MIME[ext] ?? "application/octet-stream");
+        // Vite hashes filenames under /assets/, so those are safe to cache hard.
+        if (rel.startsWith("assets/")) {
+            res.setHeader("cache-control", "public, max-age=31536000, immutable");
+        }
+        res.end(buf);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Convenience: spin up an http.Server bound to a port.
+ */
+export function createServer(opts) {
+    const handler = createHandler(opts);
+    const server = createHttpServer(handler);
+    return server;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@jslop/node-adapter",
+  "version": "0.1.0",
+  "description": "Node.js adapter for JSlop production builds. Serves the SSR render() bundle plus static assets from dist/client with long-cache headers for hashed files.",
+  "keywords": [
+    "jslop",
+    "node",
+    "adapter",
+    "ssr",
+    "framework"
+  ],
+  "license": "MIT",
+  "author": "p-arndt",
+  "homepage": "https://github.com/p-arndt/jslop#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/p-arndt/jslop.git",
+    "directory": "packages/node-adapter"
+  },
+  "bugs": "https://github.com/p-arndt/jslop/issues",
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^25.7.0",
+    "typescript": "^5.6.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  }
+}