@jk2908/solas 0.10.0 → 0.11.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.11.1
+
+### Fixes
+
+- A document request is now served as HTML by default. Solas only returns the RSC payload when the client asks for `text/x-component` (and not `text/html`); a request to a page without that, such as `Accept: */*` or no `Accept` header, used to receive the RSC payload — and, for a page with no endpoint, an error.
+
+## 0.11.0
+
+### Breaking
+
+- A route's static-params export is now `staticParams` (was `params`), matching the `Route.StaticParams` type. `Route.Prerender` became `Route.PrerenderMode` (`'full' | 'ppr'`); the `prerender` option and route export are typed `Route.PrerenderMode | false` (`false` turns prerendering off).
+
+### Features
+
+- Added build guards, installed by the adapters. An adapter declares the build features it supports (`actions`, `endpoints`) and Solas warns when the graph uses one it does not. The static adapter supports none, so it warns about server actions and `+endpoint` routes.
+
+### Fixes
+
+- The build-time prerender now shims `cloudflare:workers`, so an app that imports bindings at module scope no longer breaks the build. Bindings do not exist at build time, so reading one warns and returns `undefined`.
+
 ## 0.10.0
 
 ### Breaking

package/README.md

@@ -205,7 +205,7 @@ export const metadata: Route.Metadata<Solas.Routes['/writing/:slug']> = ({ param
 	}
 }
 
-export const params: Route.StaticParams<Solas.Routes['/writing/:slug']> = () =>
+export const staticParams: Route.StaticParams<Solas.Routes['/writing/:slug']> = () =>
 	allPosts?.map(p => ({ slug: p.__mdsrc.slug })) ?? []
 ```
 
@@ -318,10 +318,10 @@ export const prerender = false
 
 In that example, the app default is `full`, the `about` layout overrides it to `ppr`, and the page overrides it again to `false`.
 
-For dynamic routes, prerendering uses the params you export from the page:
+For dynamic routes, prerendering uses the staticParams you export from the page:
 
 ```tsx
-export const params = () => [{ id: 'post-1' }, { id: 'post-2' }]
+export const staticParams = () => [{ id: 'post-1' }, { id: 'post-2' }]
 export const prerender = 'full'
 ```
 
@@ -482,7 +482,7 @@ Use `sitemap` to generate a `sitemap.xml` at build time.
 
 Default: `false`
 
-When enabled, Solas writes a sitemap containing all routes with deterministic URLs: static routes, prerendered routes, and dynamic routes resolved via `params`. The origin for each URL comes from the resolved origin (see Config > `url`).
+When enabled, Solas writes a sitemap containing all routes with deterministic URLs: static routes, prerendered routes, and dynamic routes resolved via `staticParams`. The origin for each URL comes from the resolved origin (see Config > `url`).
 
 ```ts
 export default defineConfig(({ mode }) => ({
@@ -621,6 +621,8 @@ 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.
 
+Bindings do not exist during the build-time prerender, where Solas imports the Worker in Node with `cloudflare:workers` shimmed. Reading one then warns and returns `undefined`, so guard it with a fallback or read it at request time.
+
 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
@@ -709,6 +711,8 @@ export default defineConfig({
 
 Because it forces full prerendering, routes that need a server are not a fit: per-route PPR or SSR opt-ins and dynamic routes without `params()`.
 
+Server actions and runtime endpoints also need a server, so the build warns when the graph contains any (a `'use server'` module or a `+endpoint` file).
+
 ## Runtime
 
 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/adapters/cloudflare/runtime` builds one around the `ASSETS` binding via `createWorker`. Build-time reads and writes use `node:fs` directly and are not abstracted.

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

@@ -0,0 +1,7 @@
+import type { PrerenderImport } from '../../internal/postbuild.js';
+/**
+ * Wrap the prerender import so `cloudflare:workers` resolves to a local shim
+ * while the server bundle loads. The bundle on disk keeps the real import; this
+ * only affects the Node import Solas makes to prerender.
+ */
+export declare function withBindingsShim(next: PrerenderImport): PrerenderImport;

package/dist/adapters/cloudflare/bindings.js

@@ -0,0 +1,26 @@
+/** The shim module `cloudflare:workers` resolves to during the prerender. */
+const WORKERS_SHIM = new URL('./workers-shim.js', import.meta.url).href;
+/**
+ * Wrap the prerender import so `cloudflare:workers` resolves to a local shim
+ * while the server bundle loads. The bundle on disk keeps the real import; this
+ * only affects the Node import Solas makes to prerender.
+ */
+export function withBindingsShim(next) {
+    return async () => {
+        const { registerHooks } = await import('node:module');
+        const hooks = registerHooks({
+            resolve(specifier, context, nextResolve) {
+                if (specifier === 'cloudflare:workers') {
+                    return { url: WORKERS_SHIM, shortCircuit: true };
+                }
+                return nextResolve(specifier, context);
+            },
+        });
+        try {
+            return await next();
+        }
+        finally {
+            hooks.deregister();
+        }
+    };
+}

package/dist/adapters/cloudflare/vite.js

@@ -3,8 +3,9 @@ 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 { setPrerenderImport, setRscEntry } from '../../internal/postbuild.js';
 import { NAMESPACE_PREFIX } from './assets.js';
+import { withBindingsShim } from './bindings.js';
 const VIRTUAL_ENTRY = 'virtual:solas-cloudflare-entry';
 /**
  * Solas dependencies that are imported at request time from the Worker
@@ -127,6 +128,9 @@ export function adapter(options = {}) {
             if (rscOutDir) {
                 setRscEntry(path.resolve(cwd, rscOutDir, 'index.js'));
             }
+            // the Worker bundle imports `cloudflare:workers`, which only exists in
+            // workerd, so shim it around the Node import
+            setPrerenderImport(withBindingsShim);
         },
         configEnvironment(name, environment) {
             // Pre-bundle the Worker environments so workerd never has to re-optimize

package/dist/adapters/cloudflare/workers-shim.d.ts

@@ -0,0 +1,20 @@
+export declare const env: Record<string, unknown>;
+export declare const exports: Record<string, unknown>;
+export declare const cache: Record<string, unknown>;
+export declare const tracing: Record<string, unknown>;
+export declare function waitUntil(_promise: Promise<unknown>): void;
+export declare function withEnv<T>(_env: unknown, fn: () => T): T;
+export declare function withExports<T>(_exports: unknown, fn: () => T): T;
+export declare function withEnvAndExports<T>(_env: unknown, _exports: unknown, fn: () => T): T;
+export declare class RpcStub {
+}
+export declare class RpcTarget {
+}
+export declare class WorkerEntrypoint {
+}
+export declare class DurableObject {
+}
+export declare class WorkflowStep {
+}
+export declare class WorkflowEntrypoint {
+}

package/dist/adapters/cloudflare/workers-shim.js

@@ -0,0 +1,50 @@
+/**
+ * A stand-in for `cloudflare:workers`, loaded only while Solas imports the
+ * Worker bundle in Node for the build-time prerender (see `bindings.ts`). The
+ * real module is a workerd built-in, which Node cannot resolve.
+ *
+ * The exports mirror `@cloudflare/workers-types`' `CloudflareWorkersModule`.
+ * There are no bindings at build time, so reading one warns and returns
+ * `undefined` rather than throwing, and the classes are inert stubs so a module
+ * that extends one still loads. None of this runs on the deployed Worker.
+ */
+const warned = new Set();
+function binding() {
+    return new Proxy({}, {
+        get(_target, key) {
+            if (!warned.has(key)) {
+                warned.add(key);
+                console.warn(`[solas] "${String(key)}" was read during the build-time ` +
+                    `prerender, where no bindings exist. It returned undefined. ` +
+                    `Read it at request time, or guard it with a fallback.`);
+            }
+            return;
+        },
+    });
+}
+export const env = binding();
+export const exports = binding();
+export const cache = binding();
+export const tracing = binding();
+export function waitUntil(_promise) { }
+export function withEnv(_env, fn) {
+    return fn();
+}
+export function withExports(_exports, fn) {
+    return fn();
+}
+export function withEnvAndExports(_env, _exports, fn) {
+    return fn();
+}
+export class RpcStub {
+}
+export class RpcTarget {
+}
+export class WorkerEntrypoint {
+}
+export class DurableObject {
+}
+export class WorkflowStep {
+}
+export class WorkflowEntrypoint {
+}

package/dist/adapters/static.d.ts

@@ -14,6 +14,10 @@ export type SolasStaticOptions = {
  * then merges Solas's output into a single directory any static host can serve:
  * the client assets, the full prerenders (at their route paths) and the
  * generated `sitemap.xml` / `robots.txt`.
+ *
+ * It installs the guards with no server features supported, so the build warns
+ * when the graph contains server actions or `+endpoint` routes, which a static
+ * host cannot run.
  */
 declare function adapter(options?: SolasStaticOptions): {
     name: string;

package/dist/adapters/static.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import * as Config from '../config.js';
+import { Features, guards } from '../internal/guards.js';
 const ROOT_FILES = ['sitemap.xml', 'robots.txt'];
 /**
  * Static site adapter for Solas.
@@ -9,6 +10,10 @@ const ROOT_FILES = ['sitemap.xml', 'robots.txt'];
  * then merges Solas's output into a single directory any static host can serve:
  * the client assets, the full prerenders (at their route paths) and the
  * generated `sitemap.xml` / `robots.txt`.
+ *
+ * It installs the guards with no server features supported, so the build warns
+ * when the graph contains server actions or `+endpoint` routes, which a static
+ * host cannot run.
  */
 function adapter(options = {}) {
     const cwd = process.cwd();
@@ -39,7 +44,7 @@ function adapter(options = {}) {
             },
         },
     };
-    const plugins = [plugin];
+    const plugins = [guards(Features.None), plugin];
     return { name: 'static', plugins, prerender: 'full' };
 }
 async function exists(filePath) {

package/dist/config.d.ts

@@ -13,7 +13,8 @@ export declare const PUBLIC_DIR = "public";
 export declare const $: unique symbol;
 export declare const REQUEST_META_KEY: string;
 export declare const LOG_LEVELS: readonly ["debug", "info", "warn", "error", "fatal"];
-export declare const PRERENDER_MODES: readonly ["full", "ppr", false];
+export declare const PRERENDER_MODES: readonly ["full", "ppr"];
+export declare const PRERENDER_OPTIONS: readonly ["full", "ppr", false];
 export declare const TRAILING_SLASH_MODES: readonly ["always", "never", "ignore"];
 export declare const RUNTIME_MANIFEST = "runtime-manifest.json";
 export declare function validate(input: unknown, envUrl?: string): PluginConfig;

package/dist/config.js

@@ -12,7 +12,8 @@ export const PUBLIC_DIR = 'public';
 export const $ = Symbol(SLUG);
 export const REQUEST_META_KEY = `__${SLUG.toUpperCase()}__`;
 export const LOG_LEVELS = ['debug', 'info', 'warn', 'error', 'fatal'];
-export const PRERENDER_MODES = ['full', 'ppr', false];
+export const PRERENDER_MODES = ['full', 'ppr'];
+export const PRERENDER_OPTIONS = [...PRERENDER_MODES, false];
 export const TRAILING_SLASH_MODES = ['always', 'never', 'ignore'];
 export const RUNTIME_MANIFEST = 'runtime-manifest.json';
 const CONFIG_KEYS = new Set([
@@ -122,7 +123,7 @@ export function validate(input, envUrl) {
         }
     }
     if ('prerender' in input && input.prerender !== undefined) {
-        if (!new Set(PRERENDER_MODES).has(input.prerender)) {
+        if (!new Set(PRERENDER_OPTIONS).has(input.prerender)) {
             errors.push("prerender must be 'full', 'ppr', or false");
         }
     }

package/dist/internal/env/rsc.js

@@ -6,7 +6,7 @@ import * as Config from '../../config.js';
 import * as RuntimeManifest from '../../manifest.js';
 import { createHttpRouter } from '../http-router/create-http-router.js';
 import { HttpRouter } from '../http-router/router.js';
-import { normaliseTrailingSlash } from '../http-router/utils.js';
+import { isRscRequest, normaliseTrailingSlash } from '../http-router/utils.js';
 import { Metadata } from '../metadata.js';
 import { HttpException, isHttpException, toHttpException, toHttpExceptionLike, } from '../navigation/http-exception.js';
 import { isRedirect, toRedirect } from '../navigation/redirect.js';
@@ -190,7 +190,7 @@ export function createHandler(config, manifest, importMap, options = {}) {
         }
         const { stream: rscStream, status, ppr, } = await createPayload(req, manifest, importMap, config.metadata, opts.returnValue, opts.formState, opts.temporaryReferences);
         const stream = await rscStream;
-        if (!req.headers.get('accept')?.includes('text/html')) {
+        if (isRscRequest(req)) {
             return new Response(stream, {
                 headers: {
                     'Cache-Control': 'private, no-store',
@@ -338,14 +338,13 @@ export function createHandler(config, manifest, importMap, options = {}) {
     /**
      * Serve the saved HTML for a fully prerendered route. Runs as the route
      * handler, after middleware, so middleware applies to static routes too. It
-     * returns null for anything else (a route without a saved prerender, an RSC
-     * navigation, or a request without an HTML accept header), so the caller
-     * falls back to rendering.
+     * returns null for anything else (a route without a saved prerender or an RSC
+     * navigation), so the caller falls back to rendering.
      */
     async function serveFullPrerender(req) {
         if (import.meta.env.DEV)
             return null;
-        if (!(req.headers.get('accept') ?? '').includes('text/html'))
+        if (isRscRequest(req))
             return null;
         if (req.headers.get(`x-${Config.SLUG}-prerender-artifact`) === '1')
             return null;

package/dist/internal/guards.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Build features a platform may not support, as flags so they combine:
+ * `Features.Actions | Features.Endpoints`.
+ */
+export declare const Features: {
+    readonly None: 0;
+    readonly Actions: number;
+    readonly Endpoints: number;
+    readonly All: number;
+};
+export type Feature = (typeof Features)[keyof typeof Features];
+/**
+ * Build guards, installed by an adapter: warns when the build graph uses a
+ * feature the adapter does not support. `supports` is a set of `Features` flags
+ * (`Features.Actions | Features.Endpoints`), defaulting to `Features.All`.
+ */
+export declare function guards(supports?: Feature): {
+    name: string;
+    enforce: "pre";
+    transform(this: import("rolldown").TransformPluginContext, code: string, id: string): undefined;
+};

package/dist/internal/guards.js

@@ -0,0 +1,52 @@
+import path from 'node:path';
+import { Logger } from '../utils/logger.js';
+const logger = new Logger();
+/**
+ * Build features a platform may not support, as flags so they combine:
+ * `Features.Actions | Features.Endpoints`.
+ */
+export const Features = {
+    None: 0,
+    Actions: 1 << 0,
+    Endpoints: 1 << 1,
+    All: (1 << 0) | (1 << 1),
+};
+const LABEL = {
+    [Features.Actions]: 'a server action',
+    [Features.Endpoints]: 'a runtime endpoint',
+};
+const SOURCE = /\.(m?[jt]sx?)$/;
+const ENDPOINT = /\+endpoint\.m?[jt]sx?$/;
+const USE_SERVER = /^\s*['"]use server['"]/m;
+/**
+ * Build guards, installed by an adapter: warns when the build graph uses a
+ * feature the adapter does not support. `supports` is a set of `Features` flags
+ * (`Features.Actions | Features.Endpoints`), defaulting to `Features.All`.
+ */
+export function guards(supports = Features.All) {
+    const cwd = process.cwd();
+    const warned = new Set();
+    return {
+        name: 'solas:guards',
+        enforce: 'pre',
+        transform(code, id) {
+            const file = id.split('?')[0];
+            if (!path.isAbsolute(file) || !file.startsWith(cwd) || warned.has(file))
+                return;
+            if (!SOURCE.test(file))
+                return;
+            let feature;
+            if (ENDPOINT.test(file)) {
+                feature = Features.Endpoints;
+            }
+            else if (USE_SERVER.test(code)) {
+                feature = Features.Actions;
+            }
+            if (feature === undefined || (supports & feature) !== 0)
+                return;
+            warned.add(file);
+            logger.warn(`[build] this build uses ${LABEL[feature]} (${path.relative(cwd, file)}), ` +
+                `which the adapter does not support`);
+        },
+    };
+}

package/dist/internal/http-router/create-http-router.js

@@ -1,4 +1,5 @@
 import { HttpRouter } from './router.js';
+import { isRscRequest } from './utils.js';
 function callEndpoint(fn, req) {
     // endpoint modules may export either a zero-arg handler or one that expects the request
     if (fn.length === 0)
@@ -82,12 +83,12 @@ export function createHttpRouter(config, manifest, importMap, rsc, serveFullPrer
         const middlewares = mergeMiddlewares(importMap[page.__id]?.middlewares, endpointEntry ? importMap[endpointEntry.__id]?.middlewares : undefined);
         router.add(page.__path, 'GET', async req => {
             const accept = req.headers.get('accept') ?? '';
-            if (accept.includes('text/html') || accept.includes('text/x-component')) {
+            // a request that asks for a document or the RSC payload is rendered,
+            // as is any request to a page with no endpoint; anything else is the
+            // endpoint's own body
+            if (isRscRequest(req) || accept.includes('text/html') || !endpoint) {
                 return (await serveFullPrerender?.(req)) ?? rsc(req);
             }
-            if (!endpoint) {
-                throw new Error(`Missing unified endpoint handler for ${page.__path}`);
-            }
             return callEndpoint(endpoint, req);
         }, page.__params, middlewares);
     }

package/dist/internal/http-router/utils.d.ts

@@ -1,4 +1,12 @@
 import type { PluginConfig } from '../../types.js';
+/**
+ * Whether a request wants the RSC payload rather than a document.
+ *
+ * The client asks for `text/x-component` on navigations. Anything else (a
+ * browser, or a fetch with no explicit preference) should get HTML, so a plain
+ * request to a page never receives the RSC payload.
+ */
+export declare function isRscRequest(req: Request): boolean;
 export type PathPattern = {
     path: string;
     wildcardNames: Set<string>;

package/dist/internal/http-router/utils.js

@@ -1,3 +1,14 @@
+/**
+ * Whether a request wants the RSC payload rather than a document.
+ *
+ * The client asks for `text/x-component` on navigations. Anything else (a
+ * browser, or a fetch with no explicit preference) should get HTML, so a plain
+ * request to a page never receives the RSC payload.
+ */
+export function isRscRequest(req) {
+    const accept = req.headers.get('accept') ?? '';
+    return accept.includes('text/x-component') && !accept.includes('text/html');
+}
 /**
  * Escape a literal path segment so it can be used safely in a
  * path-to-regexp pattern.

package/dist/internal/postbuild.d.ts

@@ -1,2 +1,16 @@
+import * as Prerender from './prerender.js';
 export declare function setRscEntry(entry: string): void;
+type App = Parameters<typeof Prerender.run>[0];
+/** Imports the server bundle `postbuild` prerenders with. */
+export type PrerenderImport = () => Promise<{
+    default: App;
+}>;
+/**
+ * Set a wrapper for the import `postbuild` makes to prerender. It receives the
+ * plain import and returns one that sets up and tears down platform-specific
+ * module resolution around it, for example shimming a runtime module that Node
+ * cannot resolve (such as `cloudflare:workers`).
+ */
+export declare function setPrerenderImport(wrap: (next: PrerenderImport) => PrerenderImport): void;
 export declare function postbuild(cwd?: string): Promise<void>;
+export {};

package/dist/internal/postbuild.js

@@ -15,6 +15,16 @@ let rscEntryOverride;
 export function setRscEntry(entry) {
     rscEntryOverride = entry;
 }
+let prerenderImport;
+/**
+ * Set a wrapper for the import `postbuild` makes to prerender. It receives the
+ * plain import and returns one that sets up and tears down platform-specific
+ * module resolution around it, for example shimming a runtime module that Node
+ * cannot resolve (such as `cloudflare:workers`).
+ */
+export function setPrerenderImport(wrap) {
+    prerenderImport = wrap;
+}
 export async function postbuild(cwd = process.cwd()) {
     const manifestPath = path.join(cwd, Config.GENERATED_DIR, 'build.json');
     let manifest;
@@ -44,7 +54,10 @@ export async function postbuild(cwd = process.cwd()) {
         logger.info('[prerender]', `prerendering ${manifest.prerenderRoutes.length} routes (concurrency: ${concurrency})...`);
         const rscEntry = rscEntryOverride ?? path.join(rscDir, 'index.js');
         rscEntryOverride = undefined;
-        const { default: app } = await import(/* @vite-ignore */ rscEntry);
+        const base = () => import(/* @vite-ignore */ rscEntry);
+        const load = prerenderImport ? prerenderImport(base) : base;
+        prerenderImport = undefined;
+        const { default: app } = await load();
         async function enqueueWrite(task) {
             const write = task().finally(() => {
                 pendingWrites.delete(write);

package/dist/internal/prerender.js

@@ -270,7 +270,7 @@ export async function getStaticFlag(filePath, buildContext) {
  * in the route module and calling it to get the list of parameter objects.
  */
 export async function getStaticParams(filePath, buildContext) {
-    const params = await buildContext.exportReader.value(filePath, 'params', (v) => typeof v === 'function');
+    const params = await buildContext.exportReader.value(filePath, 'staticParams', (v) => typeof v === 'function');
     if (!params)
         return [];
     const resolved = await Promise.resolve().then(() => params());

package/dist/types.d.ts

@@ -30,11 +30,11 @@ export type Adapter = {
      * Prerender mode the platform requires, which overrides the `solas()`
      * option. A static host has no server, so it needs `'full'`.
      */
-    prerender?: Route.Prerender;
+    prerender?: Route.PrerenderMode | false;
 };
 type PluginConfigBase = {
     precompress?: boolean;
-    prerender?: Route.Prerender;
+    prerender?: Route.PrerenderMode | false;
     metadata?: Metadata.Item;
     trailingSlash?: (typeof Config.TRAILING_SLASH_MODES)[number];
     trustedOrigins?: readonly string[];
@@ -88,7 +88,7 @@ export type Segment = {
         page?: string | null;
     };
     error?: HttpException | Error;
-    prerender: Route.Prerender;
+    prerender: Route.PrerenderMode | false;
     dynamic: boolean;
     wildcard: boolean;
 };
@@ -148,7 +148,7 @@ export declare namespace Route {
     } : {
         params: ParamsOf<TRoute>;
     }) & ErrorPropsOf<TError>;
-    export type Prerender = (typeof Config.PRERENDER_MODES)[number];
+    export type PrerenderMode = (typeof Config.PRERENDER_MODES)[number];
     export {};
 }
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jk2908/solas",
-	"version": "0.10.0",
+	"version": "0.11.1",
 	"description": "A Vite + React meta-framework exploring streaming, Server Components, and partial prerendering. Designed for simplicity and lightness",
 	"keywords": [
 		"framework",
@@ -107,6 +107,7 @@
 		"path-to-regexp": "^8.3.0"
 	},
 	"devDependencies": {
+		"@cloudflare/workers-types": "^5.20261015.1",
 		"@prettier/plugin-oxc": "^0.1.3",
 		"@typescript/native-preview": "^7.0.0-dev.20260224.1",
 		"@vitejs/plugin-react": "^6.1.2",