@jk2908/solas 0.7.0 → 0.8.0-canary.1791491149398

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## Unreleased
+
+### Features
+
+- Added a platform `adapter` option to `solas()`. `solas({ adapter: cloudflare() })` registers the adapter's plugins alongside Solas's own instead of spreading them into the Vite plugins array.
+- Added a Cloudflare adapter for the Cloudflare Vite plugin beta and the `cf` CLI (`cloudflare.config.ts`). `@jk2908/solas/cloudflare/vite` exports `cloudflare()`, and `@jk2908/solas/cloudflare` exports `createWorker()` and `createCloudflareAssets()`.
+- Fully prerendered routes are now written to `dist/static` at their route paths, so a static host can serve them without invoking the server. The Cloudflare adapter copies them to the asset root.
+- Added `@jk2908/solas/node`, a `serve()` helper that runs the built handler on a Node or Bun HTTP server.
+- Request-time reads use an injected `Assets` store with logical `{ namespace, path }` references (`client`, `static`, `artifact`) instead of filesystem paths.
+
+### Breaking
+
+- Requires Vite 8 (Rolldown). The `vite` peer is now `^8.0.0`. Use Vite's `resolve.tsconfigPaths` instead of `vite-tsconfig-paths`, which breaks Rolldown's handling of the `file://` imports `@vitejs/plugin-rsc` emits.
+- Removed the `Runtime` facade (`Runtime.set`/`Runtime.reset`) and the `Runtime` export from `@jk2908/solas/env/rsc`.
+- `createHandler` now takes an options object as its fourth argument: `createHandler(config, manifest, importMap, { assets, runtimeManifest })`.
+
+### Fixes
+
+- Route modules are now executed in a standalone Vite environment resolved for `serve`, instead of a second Vite server that reloaded the config and cloned the plugin graph.
+- The Cloudflare adapter pre-bundles the Worker environments so workerd never re-optimises dependencies mid-request, which previously split React across two instances in `vite dev`.
+
 ## 0.7.0
 
 ### Breaking

package/README.md

@@ -6,11 +6,15 @@ Solas is experimental and under active development, so expect rough edges.
 
 ## Install
 
+Solas requires **Vite 8** (which uses Rolldown as the bundler).
+
 ```sh
-npm install @jk2908/solas react react-dom react-server-dom-webpack vite
-npm install -D @vitejs/plugin-react typescript vite-tsconfig-paths
+npm install @jk2908/solas react react-dom react-server-dom-webpack vite@^8
+npm install -D @vitejs/plugin-react@^6 typescript
 ```
 
+Use Vite's built-in TypeScript path resolution (`resolve.tsconfigPaths: true`) rather than `vite-tsconfig-paths`, which is not compatible with Rolldown's handling of the `file://` runtime imports the RSC plugin emits.
+
 ## Use
 
 Create a Vite config that registers Solas.
@@ -26,6 +30,20 @@ export default defineConfig({
 })
 ```
 
+Platform deployment is configured with the `adapter` option, which registers the platform's plugins alongside Solas's own instead of adding them to the plugins array:
+
+```ts
+import { defineConfig } from 'vite'
+
+import solas from '@jk2908/solas'
+import { cloudflare } from '@jk2908/solas/cloudflare/vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+	plugins: [solas({ adapter: cloudflare() }), react()],
+})
+```
+
 ## Structure
 
 Put your routes in `app/`.
@@ -507,9 +525,144 @@ export default defineConfig({
 })
 ```
 
+## Cloudflare
+
+Solas ships a Cloudflare adapter that runs the RSC server as a Worker and serves prerender artifacts and client assets through the Cloudflare assets binding.
+
+It targets the **Cloudflare Vite plugin beta** and the **`cf` CLI** workflow, where the Worker is configured by `cloudflare.config.ts`. Install the beta plugin (and `cf` for deploys):
+
+```sh
+npm install -D @cloudflare/vite-plugin@beta cf
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+
+import solas from '@jk2908/solas'
+import { cloudflare } from '@jk2908/solas/cloudflare/vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+	plugins: [solas({ prerender: 'full', adapter: cloudflare() }), react()],
+})
+```
+
+The adapter is passed to `solas()` rather than added to the plugins array directly, so platform wiring stays in one place (the same shape as SvelteKit's `sveltekit({ adapter: adapter() })`).
+
+Give the Worker a name and a compatibility date that enables `nodejs_compat`:
+
+```ts
+// cloudflare.config.ts
+import { defineConfig, defineWorker } from 'cf/config'
+
+export default defineConfig({
+	worker: defineWorker({
+		name: 'my-solas-app',
+		compatibilityDate: '2026-10-02',
+		compatibilityFlags: ['nodejs_compat'],
+	}),
+})
+```
+
+> `cloudflare.config.ts` is an open beta and must be loaded with Node 22.18+ (Bun is not supported), so the Cloudflare build and deploy commands run under Node. See the [`cf` documentation](https://developers.cloudflare.com/cf/) for the format and the `cf dev` / `cf build` / `cf deploy` commands.
+
+### Bindings
+
+Bindings are declared in `cloudflare.config.ts` and read with the standard Cloudflare global. The adapter does not manage them:
+
+```ts
+// cloudflare.config.ts
+export default defineConfig({
+	worker: defineWorker({
+		name: 'my-solas-app',
+		compatibilityDate: '2026-10-02',
+		compatibilityFlags: ['nodejs_compat'],
+		env: {
+			MY_KV: bindings.kv({ id: '...' }),
+		},
+	}),
+})
+```
+
+```tsx
+// server component
+import { env } from 'cloudflare:workers'
+
+const value = await env.MY_KV.get('key')
+```
+
+The Cloudflare Vite plugin emulates bindings in `cf dev` and `vite preview`, so there is nothing extra to configure locally.
+
+For types, the plugin writes `.cloudflare/types/index.d.ts` (bindings inferred from `cloudflare.config.ts`). Include it in `tsconfig.json` so `cloudflare:workers`'s `env` is typed:
+
+```jsonc
+{
+	"include": ["app", ".solas/*", ".cloudflare/types"],
+}
+```
+
+The adapter:
+
+- configures `@cloudflare/vite-plugin` to build the `rsc` environment as the Worker, and injects the generated entrypoint, the `ASSETS` binding, and `notFoundHandling: none` into the Worker config
+- generates the Worker entry (a virtual module) that delegates to the typed `createWorker` helper
+- points Solas's prerender step at the Cloudflare Worker bundle
+- copies `dist/static` (full prerenders at their route paths) to the asset root, so the platform serves them directly, with no Worker invocation
+- copies `dist/.solas` (runtime manifest + ppr artifacts) into the asset output at `/_solas-artifacts`
+
+Because workers have no filesystem, the Worker reads its own output through the `ASSETS` binding. Reads use logical namespaces rather than filesystem paths: `client` and `static` map onto asset-root URLs, and `artifact` maps onto the artifact prefix. Full prerenders are served by the platform; the Worker only handles dynamic routes, RSC navigation, endpoints, and the request-time `artifact` reads (manifest, ppr prelude/postponed). During the build-time prerender pass the Worker is invoked without bindings, so the Node asset store is used and reads/writes artifacts on disk.
+
+`cloudflare()` forwards its `cloudflare` option to `@cloudflare/vite-plugin`. To build a Worker manually, `createWorker` composes the entry behaviour, and `createCloudflareAssets` builds the store directly:
+
+```ts
+import { createCloudflareAssets } from '@jk2908/solas/cloudflare'
+
+const assets = createCloudflareAssets(env)
+```
+
+## Node
+
+`vite dev` and `vite preview` already run the built handler in Node (via `@vitejs/plugin-rsc`'s default server handler), so nothing extra is needed locally. For a production Node server, use `@jk2908/solas/node`:
+
+```ts
+// server.ts
+import { serve } from '@jk2908/solas/node'
+
+await serve()
+```
+
+```json
+{
+	"scripts": {
+		"build": "vite build",
+		"start": "node server.ts"
+	}
+}
+```
+
+`serve()` loads the built RSC entry (`dist/rsc/index.js` by default) and forwards requests to its fetch handler, which already serves prerendered routes, client assets, and RSC/SSR responses. Options: `port` (defaults to `PORT` or `3000`), `host`, `outDir`, and `entry`. Run from the project root so the handler can resolve `dist`.
+
+Bun and Deno do not need the helper. Their native servers pass the handler a `Request` directly and expect a `Response`, so the Node-specific HTTP-to-Fetch bridging (streams, `duplex`, backpressure) is not needed:
+
+```ts
+// Bun
+import handler from './dist/rsc/index.js'
+
+Bun.serve({ fetch: request => handler.fetch(request) })
+```
+
+```ts
+// Deno
+import handler from './dist/rsc/index.js'
+
+Deno.serve(request => handler.fetch(request))
+```
+
+The handler reads `dist` through `node:fs`, which Bun and Deno (2.x, via Node compat) provide. Run from the project root. Bun can also run `@jk2908/solas/node` as-is, since it implements `node:http`.
+
 ## Runtime
 
-This is not a deployment or packaging adapter. Platform adapters are not available yet.
+At request time Solas reads its output through an `Assets` interface (`exists`/`readText`/`readBuffer`/`mimeType`) injected into `createHandler`, defaulting to the Node standard library (which Bun runs natively). References are logical (`{ namespace, path }`), where the namespaces are `client` (Vite client output), `static` (full prerenders), and `artifact` (runtime manifest and ppr files). Platforms without a filesystem provide their own store; `@jk2908/solas/cloudflare` builds one around the `ASSETS` binding via `createWorker`. Build-time reads and writes use `node:fs` directly and are not abstracted.
 
 ## Scripts
 

package/dist/adapters/cloudflare/index.d.ts

@@ -0,0 +1,2 @@
+export { ARTIFACT_PREFIX, createCloudflareAssets, type CloudflareAssets, type CloudflareEnv, } from './runtime.js';
+export { createWorker, type CreateWorkerOptions } from './worker.js';

package/dist/adapters/cloudflare/index.js

@@ -0,0 +1,2 @@
+export { ARTIFACT_PREFIX, createCloudflareAssets, } from './runtime.js';
+export { createWorker } from './worker.js';

package/dist/adapters/cloudflare/runtime.d.ts

@@ -0,0 +1,27 @@
+import type { Assets } from '../../internal/runtimes/assets.js';
+/**
+ * The subset of the Cloudflare `assets` Fetcher binding that Solas needs.
+ */
+export type CloudflareAssets = {
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+};
+/**
+ * The bindings shape the Cloudflare asset store reads from.
+ */
+export type CloudflareEnv = {
+    ASSETS?: CloudflareAssets;
+    [key: string]: unknown;
+};
+/**
+ * Path prefix the adapter copies `dist/.solas` prerender artifacts under in the
+ * asset output.
+ */
+export declare const ARTIFACT_PREFIX = "_solas-artifacts";
+/**
+ * Create a Solas asset store backed by the Cloudflare assets binding.
+ *
+ * Workers have no writable filesystem, so this is read-only. `client` and
+ * `static` files are served from the asset root; `artifact` files are served
+ * from the adapter's artifact prefix.
+ */
+export declare function createCloudflareAssets(env: CloudflareEnv): Assets;

package/dist/adapters/cloudflare/runtime.js

@@ -0,0 +1,57 @@
+import { getMimeTypeFromPath } from '../../internal/runtimes/mime.js';
+/**
+ * Path prefix the adapter copies `dist/.solas` prerender artifacts under in the
+ * asset output.
+ */
+export const ARTIFACT_PREFIX = '_solas-artifacts';
+// The assets binding matches on pathname only, so this is only used to satisfy
+// the URL constructor
+const ASSET_ORIGIN = 'https://solas-assets.invalid';
+/**
+ * Create a Solas asset store backed by the Cloudflare assets binding.
+ *
+ * Workers have no writable filesystem, so this is read-only. `client` and
+ * `static` files are served from the asset root; `artifact` files are served
+ * from the adapter's artifact prefix.
+ */
+export function createCloudflareAssets(env) {
+    const assets = env.ASSETS;
+    if (!assets || typeof assets.fetch !== 'function') {
+        throw new Error('[solas] createCloudflareAssets requires an `ASSETS` binding. Add an assets binding to your Worker.');
+    }
+    function toUrl(asset) {
+        const path = asset.namespace === 'artifact'
+            ? `/${ARTIFACT_PREFIX}/${asset.path}`
+            : `/${asset.path}`;
+        return new URL(path, ASSET_ORIGIN).toString();
+    }
+    async function read(asset) {
+        const res = await assets.fetch(toUrl(asset), {
+            // asset responses should be passed through verbatim
+            headers: { 'accept-encoding': 'identity' },
+        });
+        return res.ok ? res : null;
+    }
+    return {
+        async exists(asset) {
+            return (await read(asset)) !== null;
+        },
+        async readText(asset) {
+            const res = await read(asset);
+            if (!res) {
+                throw new Error(`[solas] asset not found: ${asset.namespace}/${asset.path}`);
+            }
+            return res.text();
+        },
+        async readBuffer(asset) {
+            const res = await read(asset);
+            if (!res) {
+                throw new Error(`[solas] asset not found: ${asset.namespace}/${asset.path}`);
+            }
+            return res.arrayBuffer();
+        },
+        mimeType(filePath) {
+            return getMimeTypeFromPath(filePath);
+        },
+    };
+}

package/dist/adapters/cloudflare/vite.d.ts

@@ -0,0 +1,21 @@
+import { cloudflare as cloudflareVitePlugin } from '@cloudflare/vite-plugin';
+import type { Adapter } from '../../types.js';
+/**
+ * @see {@link https://developers.cloudflare.com/workers/vite-plugin/}
+ */
+type CloudflarePluginConfig = Parameters<typeof cloudflareVitePlugin>[0];
+export type SolasCloudflareOptions = {
+    /**
+     * Options forwarded to `@cloudflare/vite-plugin`.
+     */
+    cloudflare?: CloudflarePluginConfig;
+};
+/**
+ * Cloudflare adapter for Solas.
+ *
+ * Wraps `@cloudflare/vite-plugin`, generates the Worker entry that installs the
+ * asset-backed store, points Solas's prerender step at the Cloudflare Worker
+ * bundle, and copies prerender artifacts into the asset output.
+ */
+export declare function cloudflare(options?: SolasCloudflareOptions): Adapter;
+export {};

package/dist/adapters/cloudflare/vite.js

@@ -0,0 +1,146 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { cloudflare as cloudflareVitePlugin } from '@cloudflare/vite-plugin';
+import * as Config from '../../config.js';
+import { writeCloudflareEntry } from '../../internal/codegen/environments.js';
+import { setRscEntry } from '../../internal/postbuild.js';
+import { ARTIFACT_PREFIX } from './runtime.js';
+const VIRTUAL_ENTRY = 'virtual:solas-cloudflare-entry';
+/**
+ * Solas dependencies that are imported at request time from the Worker
+ * environment. They must be pre-bundled up front: the Cloudflare dev Worker
+ * runs in workerd and does not survive a mid-request dependency
+ * re-optimization, which otherwise leaves React split across two instances
+ * ("Invalid hook call").
+ */
+const WORKER_OPTIMIZE_DEPS = ['path-to-regexp'];
+async function pathExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Recursively find directories named `assets` beneath Cloudflare's build output.
+ */
+async function findAssetDirs(root, found = []) {
+    const entries = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const full = path.join(root, entry.name);
+        if (entry.name === 'assets') {
+            found.push(full);
+            continue;
+        }
+        await findAssetDirs(full, found);
+    }
+    return found;
+}
+/**
+ * Copy Solas's output into every Cloudflare asset directory:
+ * - `dist/static/**` (full prerenders) at the asset root, so the platform serves
+ *   them at their route paths before the Worker runs
+ * - `dist/.solas/**` (runtime manifest + ppr artifacts) under the artifact
+ *   prefix, read back through the `ASSETS` binding
+ */
+async function copyOutput(cwd) {
+    const outDir = path.join(cwd, Config.OUT_DIR);
+    const artifactSource = path.join(outDir, Config.GENERATED_DIR);
+    const staticSource = path.join(outDir, 'static');
+    const assetDirs = await findAssetDirs(path.join(cwd, '.cloudflare', 'output'));
+    for (const assetDir of assetDirs) {
+        if (await pathExists(artifactSource)) {
+            await fs.cp(artifactSource, path.join(assetDir, ARTIFACT_PREFIX), {
+                recursive: true,
+                force: true,
+            });
+        }
+        if (await pathExists(staticSource)) {
+            await fs.cp(staticSource, assetDir, { recursive: true, force: true });
+        }
+    }
+}
+function withAdapterConfig(config) {
+    return (workerConfig) => {
+        const base = typeof config === 'function' ? (config(workerConfig) ?? {}) : (config ?? {});
+        return {
+            ...base,
+            entrypoint: VIRTUAL_ENTRY,
+            assets: { notFoundHandling: 'none', ...base.assets },
+            env: { ...base.env, ASSETS: { type: 'assets' } },
+        };
+    };
+}
+/**
+ * Cloudflare adapter for Solas.
+ *
+ * Wraps `@cloudflare/vite-plugin`, generates the Worker entry that installs the
+ * asset-backed store, points Solas's prerender step at the Cloudflare Worker
+ * bundle, and copies prerender artifacts into the asset output.
+ */
+export function cloudflare(options = {}) {
+    const cwd = process.cwd();
+    // back the virtual entry id with a path inside the generated dir so the
+    // generated entry's relative imports (`./manifest.js`, ...) resolve
+    const virtualEntryPath = path.join(cwd, Config.GENERATED_DIR, 'entry.cloudflare.tsx');
+    const cfPlugins = cloudflareVitePlugin({
+        // Solas runs its server in the `rsc` environment; Cloudflare's worker
+        // environment must match so the RSC runtime (and its `ssr` child) is
+        // bundled into the Worker
+        viteEnvironment: { name: 'rsc', childEnvironments: ['ssr'] },
+        ...options.cloudflare,
+        config: withAdapterConfig(options.cloudflare?.config),
+    });
+    const adapter = {
+        name: 'solas-cloudflare',
+        enforce: 'post',
+        configResolved(config) {
+            // the Cloudflare plugin points the `rsc` environment's build output at
+            // the Worker bundle during its `config` hook, so by now we know where
+            // Solas's prerender step should import the Worker from
+            const rscOutDir = config.environments.rsc?.build.outDir;
+            if (rscOutDir) {
+                setRscEntry(path.resolve(cwd, rscOutDir, 'index.js'));
+            }
+        },
+        configEnvironment(name, environment) {
+            // Pre-bundle the Worker environments so workerd never has to re-optimize
+            // dependencies in the middle of a request. Scanning the app directory
+            // surfaces any additional request-time dependencies too
+            if (name !== 'rsc' && name !== 'ssr')
+                return;
+            environment.optimizeDeps ??= {};
+            environment.optimizeDeps.include = [
+                ...new Set([
+                    ...(environment.optimizeDeps.include ?? []),
+                    ...WORKER_OPTIMIZE_DEPS,
+                ]),
+            ];
+            environment.optimizeDeps.entries = [
+                ...new Set([
+                    ...(environment.optimizeDeps.entries ?? []),
+                    `${Config.APP_DIR}/**/*.{tsx,ts,jsx,js}`,
+                ]),
+            ];
+        },
+        resolveId(source) {
+            return source === VIRTUAL_ENTRY ? virtualEntryPath : null;
+        },
+        load(id) {
+            return id === virtualEntryPath ? writeCloudflareEntry() : null;
+        },
+        buildApp: {
+            order: 'post',
+            async handler() {
+                // runs after Solas's own `post` buildApp (adapter comes later in the
+                // plugin array), so `dist/.solas` artifacts already exist
+                await copyOutput(cwd);
+            },
+        },
+    };
+    return { name: 'cloudflare', plugins: [adapter, ...cfPlugins] };
+}

package/dist/adapters/cloudflare/worker.d.ts

@@ -0,0 +1,18 @@
+import type { ImportMap, Manifest, RuntimeConfig } from '../../types.js';
+import { type CloudflareEnv } from './runtime.js';
+export type CreateWorkerOptions = {
+    config: RuntimeConfig;
+    manifest: Manifest;
+    importMap: ImportMap;
+};
+/**
+ * Build a Cloudflare Worker around Solas's RSC handler.
+ *
+ * The asset store and handler depend on `env`, so handlers are cached per `env`
+ * (not once per isolate). A failed build is evicted so a transient error does
+ * not poison the Worker. During build-time prerender the Worker is invoked
+ * without bindings, in which case the Node asset store is used.
+ */
+export declare function createWorker(options: CreateWorkerOptions): {
+    fetch(request: Request, env?: CloudflareEnv | undefined, _ctx?: unknown): Promise<Response>;
+};

package/dist/adapters/cloudflare/worker.js

@@ -0,0 +1,46 @@
+import { createHandler, loadManifest } from '../../internal/env/rsc.js';
+import { nodeAssets } from '../../internal/runtimes/assets.js';
+import { createCloudflareAssets } from './runtime.js';
+/**
+ * Build a Cloudflare Worker around Solas's RSC handler.
+ *
+ * The asset store and handler depend on `env`, so handlers are cached per `env`
+ * (not once per isolate). A failed build is evicted so a transient error does
+ * not poison the Worker. During build-time prerender the Worker is invoked
+ * without bindings, in which case the Node asset store is used.
+ */
+export function createWorker(options) {
+    const handlers = new WeakMap();
+    let nodeHandler;
+    async function build(assets) {
+        const runtimeManifest = await loadManifest(assets);
+        return createHandler(options.config, options.manifest, options.importMap, {
+            assets,
+            runtimeManifest,
+        });
+    }
+    function getHandler(env) {
+        if (!env) {
+            nodeHandler ??= build(nodeAssets).catch(err => {
+                nodeHandler = undefined;
+                throw err;
+            });
+            return nodeHandler;
+        }
+        let promise = handlers.get(env);
+        if (!promise) {
+            promise = build(createCloudflareAssets(env)).catch(err => {
+                handlers.delete(env);
+                throw err;
+            });
+            handlers.set(env, promise);
+        }
+        return promise;
+    }
+    return {
+        async fetch(request, env, _ctx) {
+            const handler = await getHandler(env);
+            return handler.fetch(request);
+        },
+    };
+}

package/dist/adapters/node.d.ts

@@ -0,0 +1,43 @@
+import http from 'node:http';
+export type ServeOptions = {
+    /**
+     * Port to listen on. Defaults to `process.env.PORT` or `3000`.
+     */
+    port?: number;
+    /**
+     * Host to bind to. Defaults to `0.0.0.0`.
+     */
+    host?: string;
+    /**
+     * Build output directory the handler reads from. Defaults to `dist`, resolved
+     * relative to the current working directory.
+     */
+    outDir?: string;
+    /**
+     * Explicit path to the built RSC entry. Defaults to `<outDir>/rsc/index.js`.
+     */
+    entry?: string;
+    /**
+     * Called once the server is listening.
+     */
+    onListen?: (info: {
+        port: number;
+        host: string;
+    }) => void;
+};
+export type Server = http.Server & AsyncDisposable;
+/**
+ * Start a production HTTP server for a Node (or Bun) deployment.
+ *
+ * Loads the built RSC entry (`dist/rsc/index.js` by default) and forwards
+ * requests to its fetch handler, which already serves prerendered routes,
+ * client assets, and RSC/SSR responses. Run it from the project root so the
+ * handler can resolve `dist`. The returned server is `AsyncDisposable`, so it
+ * can be released with `await using`.
+ *
+ * Deno and Bun do not need this helper: use `Deno.serve(handler.fetch)` or
+ * `Bun.serve({ fetch: handler.fetch })` directly.
+ */
+export declare function serve(options?: ServeOptions): Promise<http.Server<typeof http.IncomingMessage, typeof http.ServerResponse> & {
+    [Symbol.asyncDispose](): Promise<void>;
+}>;