@foldkit/vite-plugin 0.13.1 → 0.15.0

package/README.md

@@ -53,6 +53,16 @@ The plugin uses Vite's WebSocket connection to communicate between the dev serve
 
 Model is preserved across hot reloads but cleared on manual browser refreshes, giving you control over when to reset your app.
 
+## Server rendering dev host
+
+Pass `ssr` with the path to your server entry to render page requests through it during development:
+
+```typescript
+plugins: [foldkit({ ssr: { serverEntry: '/src/entry.server.ts' } })]
+```
+
+With this set, the dev server converts HTML page requests to Web `Request` values, passes them to the entry's `renderPage`, and serves the returned `Response`. Vite continues to serve the client entry, HMR, and assets, and the server entry runs through Vite's module graph, so edits to it apply without a restart. The client side of the handoff needs no plugin configuration: a server-rendered application's client entry calls `Runtime.hydrate` instead of `Runtime.run`, and hydrate adopts the served HTML in place. The option shapes only the dev server; production hosts import the built server entry themselves. See the [Server Rendering documentation](https://foldkit.dev/core/server-rendering) for the full contract.
+
 ## DevTools overlay
 
 When `@foldkit/devtools` is installed as a development dependency, the plugin mounts its overlay automatically during development and leaves it out of production builds. No application import or `devTools.overlay` field is needed.

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import type { Plugin } from 'vite';
+import { type FoldkitSsrOptions } from './ssr.js';
 export { type BrandDistResult, brandDistDirectory } from './brandDist.js';
+export { type FoldkitSsrOptions, foldkitSsr } from './ssr.js';
 export { type ViewIdentityTransformResult, foldkitViewIdentity, transformViewIdentity, } from './viewIdentity.js';
 /** Options for the `foldkit` Vite plugin. */
 export type FoldkitPluginOptions = Readonly<{
@@ -10,6 +12,13 @@ export type FoldkitPluginOptions = Readonly<{
      * the Foldkit DevTools MCP server.
      */
     devToolsMcpPort?: number;
+    /**
+     * Serve server-rendered pages from the Vite dev server. When set, `vite`
+     * passes HTML navigations that fall through Vite, plus non-GET requests, to
+     * `renderPage` from the module at `ssr.serverEntry`. When `undefined` (the
+     * default), the dev server serves the client entry only.
+     */
+    ssr?: FoldkitSsrOptions;
 }>;
 /**
  * Foldkit's Vite plugin set: the view-identity branding transform and

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EACV,MAAM,EAIP,MAAM,MAAM,CAAA;AAMb,OAAO,EAAE,KAAK,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AACzE,OAAO,EACL,KAAK,2BAA2B,EAChC,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,mBAAmB,CAAA;AAE1B,6CAA6C;AAC7C,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB,CAAC,CAAA;AAilBF;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,GAAI,UAAS,oBAAyB,KAAG,KAAK,CAAC,MAAM,CA6DxE,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EACV,MAAM,EAIP,MAAM,MAAM,CAAA;AAIb,OAAO,EAAE,KAAK,iBAAiB,EAAc,MAAM,UAAU,CAAA;AAG7D,OAAO,EAAE,KAAK,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AACzE,OAAO,EAAE,KAAK,iBAAiB,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC7D,OAAO,EACL,KAAK,2BAA2B,EAChC,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,mBAAmB,CAAA;AAE1B,6CAA6C;AAC7C,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,iBAAiB,CAAA;CACxB,CAAC,CAAA;AAilBF;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,GAAI,UAAS,oBAAyB,KAAG,KAAK,CAAC,MAAM,CAoExE,CAAA"}

package/dist/index.js

@@ -5,8 +5,10 @@ import { createRequire } from 'node:module';
 import { resolve } from 'node:path';
 import { WebSocketServer } from 'ws';
 import { devToolsOverlayPlugin } from './devToolsOverlay.js';
+import { foldkitSsr } from './ssr.js';
 import { foldkitViewIdentity } from './viewIdentity.js';
 export { brandDistDirectory } from './brandDist.js';
+export { foldkitSsr } from './ssr.js';
 export { foldkitViewIdentity, transformViewIdentity, } from './viewIdentity.js';
 // NOTE: Vite's dep optimizer scans the consumer's source for `effect`
 // imports and pre-bundles only those exports into a single `effect.js`
@@ -374,5 +376,12 @@ export const foldkit = (options = {}) => {
             return [];
         },
     };
-    return [foldkitViewIdentity(), devToolsOverlayPlugin(), hmrPlugin];
+    return options.ssr === undefined
+        ? [foldkitViewIdentity(), devToolsOverlayPlugin(), hmrPlugin]
+        : [
+            foldkitViewIdentity(),
+            devToolsOverlayPlugin(),
+            hmrPlugin,
+            foldkitSsr(options.ssr),
+        ];
 };

package/dist/ssr.d.ts

@@ -0,0 +1,27 @@
+import type { Plugin } from 'vite';
+/** Options for serving server-rendered pages from the Vite dev server. */
+export type FoldkitSsrOptions = Readonly<{
+    /**
+     * Module path of the server entry, resolved by Vite (e.g.
+     * `'/src/entry.server.ts'`). The module must export a `renderPage`
+     * function taking a Web `Request` and returning a
+     * `Promise<EntryResult>`.
+     */
+    serverEntry: string;
+    /**
+     * The `id` of the empty container element in `index.html` the rendered
+     * markup replaces. Defaults to `'root'`.
+     */
+    containerId?: string;
+}>;
+/**
+ * Serves server-rendered pages from the Vite dev server.
+ *
+ * Registered after Vite's own middleware, so the client entry, HMR, and
+ * assets are untouched. HTML navigations that fall through, plus non-GET
+ * requests, load the server entry through Vite's SSR module loader, call its
+ * `renderPage` with a Web `Request`, and send the resulting Web `Response`.
+ * Server entry edits take effect without a restart.
+ */
+export declare const foldkitSsr: (options: FoldkitSsrOptions) => Plugin;
+//# sourceMappingURL=ssr.d.ts.map

package/dist/ssr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssr.d.ts","sourceRoot":"","sources":["../src/ssr.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAW,MAAM,EAAiB,MAAM,MAAM,CAAA;AAE1D,0EAA0E;AAC1E,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC;;;;;OAKG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAC,CAAA;AAyLF;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,GAAI,SAAS,iBAAiB,KAAG,MA+CtD,CAAA"}

package/dist/ssr.js

@@ -0,0 +1,153 @@
+import { Array, Effect, Predicate } from 'effect';
+import { Server } from 'foldkit/experimental';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { Readable } from 'node:stream';
+const isEntryModule = (loadedModule) => Predicate.isObject(loadedModule) &&
+    Predicate.hasProperty(loadedModule, 'renderPage') &&
+    Predicate.isFunction(loadedModule.renderPage);
+const toWebRequest = (url, nodeRequest) => {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(nodeRequest.headers)) {
+        if (Predicate.isString(value)) {
+            headers.set(name, value);
+        }
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                headers.append(name, item);
+            }
+        }
+    }
+    const host = nodeRequest.headers.host ?? 'localhost';
+    const method = nodeRequest.method ?? 'GET';
+    const requestInit = { headers, method };
+    if (method !== 'GET' && method !== 'HEAD') {
+        // NOTE: Node and the DOM library declare structurally different
+        // ReadableStream interfaces even though Node's `Readable.toWeb` returns
+        // the Web stream implementation that `Request` consumes at runtime.
+        requestInit.body = Readable.toWeb(nodeRequest);
+        requestInit.duplex = 'half';
+    }
+    return new Request(new URL(url, `http://${host}`), requestInit);
+};
+const renderDecision = (nodeRequest) => {
+    const method = nodeRequest.method ?? 'GET';
+    const url = nodeRequest.originalUrl ?? nodeRequest.url ?? '/';
+    if (method === 'GET' || method === 'HEAD') {
+        if (Server.resolvesToIndexHtml(url)) {
+            return 'Render';
+        }
+        const accept = nodeRequest.headers.accept;
+        return Server.acceptsHtml(Predicate.isString(accept) ? accept : undefined)
+            ? 'RenderVaryAccept'
+            : 'RefusedVaryAccept';
+    }
+    if (method === 'OPTIONS' || method === 'TRACE') {
+        return 'Skip';
+    }
+    return 'Render';
+};
+const renderRequest = (server, options, nodeRequest) => Effect.gen(function* () {
+    const url = nodeRequest.originalUrl ?? nodeRequest.url ?? '/';
+    const rawTemplate = yield* Effect.promise(() => readFile(resolve(server.config.root, 'index.html'), 'utf-8'));
+    // NOTE: the first argument tells Vite where the HTML lives, and Vite
+    // resolves the template's relative URLs (such as a `./src/entry.ts`
+    // script) against it. The template always lives at the site root, so
+    // that argument must stay `/index.html` no matter which route is being
+    // rendered. The third argument, named `originalUrl` in Vite's signature,
+    // carries the route actually being requested.
+    const template = yield* Effect.promise(() => server.transformIndexHtml('/index.html', rawTemplate, url));
+    const loadedModule = yield* Effect.promise(() => server.ssrLoadModule(options.serverEntry));
+    if (!isEntryModule(loadedModule)) {
+        return yield* Effect.die(new Error(`[foldkit] '${options.serverEntry}' does not export a renderPage function, so the dev server cannot render pages.`));
+    }
+    const result = yield* Effect.promise(() => loadedModule.renderPage(toWebRequest(url, nodeRequest)));
+    return Server.toResponse(template, result, options.containerId === undefined
+        ? {}
+        : { containerId: options.containerId });
+});
+const varyHeaderValue = (value) => {
+    if (Array.isArray(value)) {
+        return value.join(', ');
+    }
+    if (typeof value === 'string') {
+        return value;
+    }
+    return undefined;
+};
+const sendWebResponse = async (webResponse, nodeRequest, nodeResponse, varyAccept) => {
+    nodeResponse.statusCode = webResponse.status;
+    if (webResponse.statusText !== '') {
+        nodeResponse.statusMessage = webResponse.statusText;
+    }
+    const getSetCookie = Predicate.hasProperty(webResponse.headers, 'getSetCookie')
+        ? webResponse.headers.getSetCookie
+        : undefined;
+    const setCookieHeaders = Predicate.isFunction(getSetCookie)
+        ? getSetCookie.call(webResponse.headers)
+        : [];
+    for (const [name, value] of webResponse.headers) {
+        if (name !== 'set-cookie' || Array.isArrayEmpty(setCookieHeaders)) {
+            nodeResponse.setHeader(name, value);
+        }
+    }
+    if (Array.isArrayNonEmpty(setCookieHeaders)) {
+        nodeResponse.setHeader('set-cookie', setCookieHeaders);
+    }
+    if (varyAccept) {
+        // Merge into whatever Vary already sits on the node response (the app's
+        // own, plus Vite's own Vary: Origin), so declaring Accept does not drop it.
+        nodeResponse.setHeader('vary', Server.varyWithAccept(varyHeaderValue(nodeResponse.getHeader('vary'))));
+    }
+    if (nodeRequest.method === 'HEAD' || webResponse.body === null) {
+        nodeResponse.end();
+    }
+    else {
+        const body = new Uint8Array(await webResponse.arrayBuffer());
+        nodeResponse.end(body);
+    }
+};
+/**
+ * Serves server-rendered pages from the Vite dev server.
+ *
+ * Registered after Vite's own middleware, so the client entry, HMR, and
+ * assets are untouched. HTML navigations that fall through, plus non-GET
+ * requests, load the server entry through Vite's SSR module loader, call its
+ * `renderPage` with a Web `Request`, and send the resulting Web `Response`.
+ * Server entry edits take effect without a restart.
+ */
+export const foldkitSsr = (options) => ({
+    name: 'foldkit-ssr',
+    // NOTE: `vite preview` also resolves with command 'serve', but it serves
+    // built output and never runs configureServer, so applying there would
+    // only set appType 'custom' and strip preview's HTML middleware.
+    apply: (_config, env) => env.command === 'serve' && env.isPreview !== true,
+    config: () => ({ appType: 'custom' }),
+    configureServer: server => () => {
+        server.middlewares.use((nodeRequest, nodeResponse, next) => {
+            const decision = renderDecision(nodeRequest);
+            if (decision === 'Skip') {
+                next();
+                return;
+            }
+            if (decision === 'RefusedVaryAccept') {
+                // The 404 depends on Accept (an HTML-accepting client would have
+                // rendered), so it varies on Accept for a shared cache, the same as
+                // a production host's refused response.
+                nodeResponse.statusCode = 404;
+                nodeResponse.setHeader('vary', Server.varyWithAccept(varyHeaderValue(nodeResponse.getHeader('vary'))));
+                nodeResponse.end();
+                return;
+            }
+            const varyAccept = decision === 'RenderVaryAccept';
+            void Effect.runPromise(renderRequest(server, options, nodeRequest))
+                .then(response => sendWebResponse(response, nodeRequest, nodeResponse, varyAccept))
+                .catch((error) => {
+                if (error instanceof Error) {
+                    server.ssrFixStacktrace(error);
+                }
+                next(error);
+            });
+        });
+    },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldkit/vite-plugin",
-  "version": "0.13.1",
+  "version": "0.15.0",
   "description": "Vite plugin for Foldkit hot module reloading with state preservation",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,7 +16,7 @@
     "dist"
   ],
   "peerDependencies": {
-    "effect": "4.0.0-rc.108",
+    "effect": "4.0.0-rc.109",
     "foldkit": "^0",
     "vite": "^7.0.0 || ^8.0.0"
   },
@@ -27,13 +27,13 @@
   "devDependencies": {
     "@types/node": "^25.9.3",
     "@types/ws": "^8.18.1",
-    "effect": "4.0.0-rc.108",
+    "effect": "4.0.0-rc.109",
     "happy-dom": "^20.10.4",
     "rimraf": "^6.1.3",
     "typescript": "^6.0.3",
     "vite": "^8.0.16",
     "vitest": "^4.1.9",
-    "foldkit": "0.145.0"
+    "foldkit": "0.147.0"
   },
   "keywords": [
     "vite",