filesystem-routing 0.2.0 → 0.3.0

package/README.md

@@ -241,8 +241,14 @@ The scanner produces flat `RouteManifestEntry` objects:
 
 The Vite adapter serializes the manifest into the virtual module, turning
 `$`-prefixed refs into dynamic imports and `$$`-prefixed refs into static
-imports, each tree-shaken down to the picked exports. It serves two views of
-the same entries:
+imports, each tree-shaken down to the picked exports. Splitting is not always
+a win — on a small app the per-chunk overhead can leave the split bundle
+larger — so `fileRoutes({ codeSplitting: false })` delivers `$` refs eagerly
+too (`{ src, require }`, statically imported); emission adapters branch on
+the delivered shape, so no second switch exists on their side. With
+`@solidjs/router` this requires the next release (newer than
+`2.0.0-next.14`) — against `next.14` or older, enabling the option fails at
+first render. The module serves two views of the same entries:
 
 ```ts
 import routes, { pageRoutes } from "virtual:file-routes";
@@ -305,6 +311,7 @@ fileRoutes({
 | `httpMethods` | emit `$GET`, `$POST`, … refs for uppercase handler exports; a module with handlers but no default export routes without being a page |
 | `components` | set `false` to route without emitting `$component` refs, keeping page modules out of that environment's bundle |
 | `buildInputs` | environments whose build takes every code-split route module as an entry |
+| `codeSplitting` | set `false` to deliver every module ref as an eager static import — no `lazy()` components, zero dynamic imports, one bundle — for small apps where per-chunk overhead outweighs the split (defaults to `true`; with `@solidjs/router` requires the next release, newer than `2.0.0-next.14`) |
 | `moduleId` | the id the manifest is served from |
 | `optimizeDepsExclude` | escape hatch for packages that import the virtual module, kept out of dep prebundling (defaults to `[]`) |
 | `types` | write a declaration typing the manifest as a literal tuple, kept in step with the route directory |

package/dist/analyze.js

@@ -1,5 +1,21 @@
 import fs from "node:fs";
+import { createRequire } from "node:module";
 import { parseSync } from "oxc-parser";
+let tsrxParseSync;
+function loadTsrxParser(src) {
+    if (!tsrxParseSync) {
+        try {
+            const facade = createRequire(import.meta.url)("@tsrx/oxc/parser");
+            tsrxParseSync = facade.parseSync;
+        }
+        catch (cause) {
+            throw new Error(`Cannot analyze the TSRX route module ${src}: analyzing .tsrx exports requires ` +
+                `the optional peer dependency @tsrx/oxc. Install it (npm i -D @tsrx/oxc) ` +
+                `or keep route modules in .ts/.tsx.`, { cause });
+        }
+    }
+    return tsrxParseSync;
+}
 /**
  * Analyze a route module's static exports.
  *
@@ -8,7 +24,23 @@ import { parseSync } from "oxc-parser";
  * a compiler that already performs export analysis can provide it instead.
  */
 export function analyzeModule(src) {
-    const result = parseSync(src, fs.readFileSync(src, "utf-8"), { lang: "tsx" });
+    const source = fs.readFileSync(src, "utf-8");
+    let result;
+    if (src.endsWith(".tsrx")) {
+        const parse = loadTsrxParser(src);
+        // The TSRX facade reports most syntax errors through `result.errors` but
+        // throws on some malformed sources; normalize both into the same shape.
+        try {
+            result = parse(src, source, { lang: "tsrx" });
+        }
+        catch (cause) {
+            const message = cause instanceof Error ? cause.message : String(cause);
+            throw new SyntaxError(`Failed to parse ${src}:\n${message}`, { cause });
+        }
+    }
+    else {
+        result = parseSync(src, source, { lang: "tsx" });
+    }
     const error = result.errors[0];
     if (error)
         throw new SyntaxError(`Failed to parse ${src}:\n${error.codeframe || error.message}`);

package/dist/api.d.ts

@@ -39,9 +39,15 @@ export interface FileRouteHandlers {
     $DELETE?: APIHandlerRef;
     [key: string]: unknown;
 }
-export interface APIHandlerRef {
+/**
+ * A handler module ref as delivered: code-split (`import()`) by default,
+ * eager (`require()`) when the delivery adapter runs with code splitting off.
+ */
+export type APIHandlerRef = {
     import(): Promise<Record<string, APIHandler>>;
-}
+} | {
+    require(): Record<string, APIHandler>;
+};
 export interface APIMatch {
     handler: APIHandlerRef;
     params?: Record<string, string>;

package/dist/api.js

@@ -101,7 +101,7 @@ export function createAPIHandler(routes, options = {}) {
         const matched = match(stripPathBase(url.pathname, options.base ?? "/"), request.method);
         if (!matched)
             return next();
-        const mod = await matched.handler.import();
+        const mod = "require" in matched.handler ? matched.handler.require() : await matched.handler.import();
         const fn = request.method === "HEAD" ? mod.HEAD || mod.GET : mod[request.method];
         if (typeof fn !== "function")
             return next();

package/dist/manifest.d.ts

@@ -16,6 +16,11 @@
  * under decides how:
  * - keys prefixed `$` become lazy refs: `{ src, import: () => import(...) }`
  * - keys prefixed `$$` become eager refs: `{ require: () => ({ ...exports }) }`
+ *
+ * A delivery adapter configured without code splitting (the Vite adapter's
+ * `codeSplitting: false`) materializes `$` refs eagerly too, as
+ * `{ src, require }` — the delivered shape, not the key prefix, is the
+ * contract consumers branch on.
  */
 export interface ModuleRef {
     /** Absolute path of the source module. */

package/dist/vite/constants.js

@@ -5,4 +5,4 @@
  * not tied to any router. Override it with the plugin's `moduleId` option.
  */
 export const moduleId = "virtual:file-routes";
-export const DEFAULT_EXTENSIONS = ["js", "jsx", "ts", "tsx"];
+export const DEFAULT_EXTENSIONS = ["js", "jsx", "ts", "tsx", "tsrx"];

package/dist/vite/index.d.ts

@@ -32,6 +32,21 @@ export interface FileRoutesOptions extends Pick<PageFileSystemRouterConfig, "com
      * framework already configures.
      */
     buildInputs?: string | string[];
+    /**
+     * Deliver `$`-prefixed module refs as code-split dynamic imports, each
+     * route its own chunk. The default. Set to `false` to deliver every ref
+     * eagerly instead — static imports, `require()`-shaped refs, zero dynamic
+     * imports in the output — for the apps where splitting loses: small apps
+     * whose per-chunk overhead outweighs the split, and targets that want a
+     * single bundle. Adapters need no switch of their own: refs are
+     * self-describing (`import()` is code-split, `require()` is eager), and
+     * emission adapters branch on the shape they are handed.
+     *
+     * With `@solidjs/router`, `codeSplitting: false` requires the next release
+     * (newer than `2.0.0-next.14`): its adapter must branch on eager refs, and
+     * against `next.14` or older, enabling this option fails at first render.
+     */
+    codeSplitting?: boolean;
     /**
      * Packages that import the virtual module and must therefore stay out of
      * esbuild's dependency prebundling, which cannot resolve it. Emission
@@ -65,5 +80,11 @@ export interface FileRoutesOptions extends Pick<PageFileSystemRouterConfig, "com
  * flat manifest, and `pageRoutes` is the page entries nested by path with
  * `(group)` segments stripped, so emission adapters don't each reimplement
  * the tree.
+ *
+ * With `httpMethods` on, one router serves both sides of an SSR app: the
+ * handler refs it emits reach server-consumer environments only, and client
+ * manifests drop them (and handler-only API entries with them) so handler
+ * modules never enter a client build. An environment given its own router
+ * via `routers` is explicit and serves that router's manifest untouched.
  */
 export declare function fileRoutes(options?: FileRoutesOptions): PluginOption[];

package/dist/vite/index.js

@@ -10,6 +10,45 @@ import { serializeTypes } from "./types.js";
 export { DEFAULT_EXTENSIONS, moduleId };
 export { sanitizeChunkFileName, toPickId, treeShake } from "./tree-shake.js";
 export { fileSystemWatcher } from "./fs-watcher.js";
+/**
+ * Handler refs are the `$`-prefixed all-uppercase keys the convention emits
+ * (`$GET`, `$POST`, ...). They exist for server dispatch only.
+ */
+const HANDLER_REF = /^\$[A-Z]+$/;
+/**
+ * Whether a Vite environment runs on the server. `configEnvironment` sees
+ * `consumer` only when something set it explicitly, so fall back to Vite's
+ * own default: the `client` environment is the one client consumer.
+ */
+const isServerConsumer = (name, consumer) => (consumer ?? (name === "client" ? "client" : "server")) === "server";
+/**
+ * The client's view of a shared server manifest: handler refs removed. A
+ * client bundle can never invoke a request handler, but serializing its ref
+ * would pull the handler module — and the server-only code it imports —
+ * into the client build. Handler-only entries (API routes) disappear
+ * entirely; pages that also export handlers keep their page refs.
+ */
+function stripHandlerRefs(routes) {
+    const stripped = [];
+    for (const route of routes) {
+        const handlerKeys = Object.keys(route).filter(key => HANDLER_REF.test(key));
+        if (!handlerKeys.length) {
+            stripped.push(route);
+            continue;
+        }
+        const rest = { ...route };
+        for (const key of handlerKeys)
+            delete rest[key];
+        // Entries carry `$component: undefined` placeholders; only a ref with a
+        // value keeps a handler-only entry alive. Otherwise not even the API
+        // path string reaches the client bundle.
+        if (rest.page ||
+            Object.keys(rest).some(key => key.startsWith("$") && rest[key] !== undefined)) {
+            stripped.push(rest);
+        }
+    }
+    return stripped;
+}
 /**
  * The Vite delivery adapter for `filesystem-routing`.
  *
@@ -22,9 +61,16 @@ export { fileSystemWatcher } from "./fs-watcher.js";
  * flat manifest, and `pageRoutes` is the page entries nested by path with
  * `(group)` segments stripped, so emission adapters don't each reimplement
  * the tree.
+ *
+ * With `httpMethods` on, one router serves both sides of an SSR app: the
+ * handler refs it emits reach server-consumer environments only, and client
+ * manifests drop them (and handler-only API entries with them) so handler
+ * modules never enter a client build. An environment given its own router
+ * via `routers` is explicit and serves that router's manifest untouched.
  */
 export function fileRoutes(options = {}) {
     const virtualId = options.moduleId ?? moduleId;
+    const codeSplitting = options.codeSplitting !== false;
     const buildInputs = options.buildInputs === undefined
         ? []
         : Array.isArray(options.buildInputs)
@@ -47,7 +93,7 @@ export function fileRoutes(options = {}) {
         if (!file || !router)
             return;
         const routes = (await router.getRoutes()) ?? [];
-        const contents = serializeTypes(virtualId, routes, buildRouteTree(routes.filter(route => route.page)), dirname(file));
+        const contents = serializeTypes(virtualId, routes, buildRouteTree(routes.filter(route => route.page)), dirname(file), codeSplitting);
         // Only touch the file when it actually changes: every environment calls
         // this, and rewriting it would churn the watcher for no reason.
         let previous;
@@ -101,16 +147,27 @@ export function fileRoutes(options = {}) {
                 await writeTypes();
             },
             async configEnvironment(name, _config, env) {
+                // Without code splitting no ref becomes a dynamic import, so no
+                // route module needs to be an entry: they are all statically
+                // reachable from the virtual module.
+                if (!codeSplitting)
+                    return;
                 if (env.command !== "build" || !buildInputs.includes(name))
                     return;
                 const router = getRouter(name);
                 if (!router)
                     return;
+                // A client environment on the shared router never serializes
+                // handler refs (see load), so their modules must not become its
+                // build entries either.
+                const routes = options.routers?.[name] || isServerConsumer(name, _config.consumer)
+                    ? await router.getRoutes()
+                    : stripHandlerRefs(await router.getRoutes());
                 // Every code-split route module is an entry of its own, so the
                 // manifest's dynamic imports resolve to real chunks. `$$` refs are
                 // inlined into the manifest and need no entry.
                 const input = [];
-                for (const route of await router.getRoutes()) {
+                for (const route of routes) {
                     for (const [key, ref] of Object.entries(route)) {
                         if (ref && key.startsWith("$") && !key.startsWith("$$")) {
                             input.push(toModuleId(ref));
@@ -131,8 +188,17 @@ export function fileRoutes(options = {}) {
                 const root = this.environment.config.root;
                 const isBuild = this.environment.mode === "build";
                 const js = jsCode();
-                const router = getRouter(this.environment.name);
-                const routes = (router ? await router.getRoutes() : []) ?? [];
+                const environmentName = this.environment.name;
+                const router = getRouter(environmentName);
+                let routes = (router ? await router.getRoutes() : []) ?? [];
+                // The shared router serves every environment, so the split is this
+                // adapter's job: client consumers get the manifest without handler
+                // refs. An explicit per-environment router already IS the split —
+                // serve whatever it emits.
+                if (!options.routers?.[environmentName] &&
+                    !isServerConsumer(environmentName, this.environment.config.consumer)) {
+                    routes = stripHandlerRefs(routes);
+                }
                 const serializeEntry = (entry) => JSON.stringify(entry, (key, value) => {
                     if (value === undefined)
                         return undefined;
@@ -150,6 +216,16 @@ export function fileRoutes(options = {}) {
                     }
                     else if (key.startsWith("$")) {
                         const buildId = toModuleId(value);
+                        // With code splitting off the ref is delivered eagerly: a
+                        // namespace import (named imports would fail on the synthetic
+                        // `$css` pick) behind the `require()` shape eager refs carry,
+                        // plus the `src` lazy refs already expose.
+                        if (!codeSplitting) {
+                            return {
+                                src: relative(root, buildId),
+                                require: `_$() => (${js.addNamespaceImport(buildId)})$_`
+                            };
+                        }
                         return {
                             src: relative(root, buildId),
                             build: isBuild ? `_$() => import('${buildId}')$_` : undefined,
@@ -192,6 +268,7 @@ export const pageRoutes = ${serializeTree(tree)};
 }
 function jsCode() {
     const imports = new Map();
+    const namespaceImports = new Map();
     let vars = 0;
     function addNamedImport(name, source) {
         let names = imports.get(source);
@@ -208,15 +285,25 @@ function jsCode() {
         names[name] = alias;
         return alias;
     }
+    function addNamespaceImport(source) {
+        const existing = namespaceImports.get(source);
+        if (existing)
+            return existing;
+        const alias = "routeModule" + namespaceImports.size;
+        namespaceImports.set(source, alias);
+        return alias;
+    }
     const getImportStatements = () => {
-        return [...imports.entries()]
-            .map(([source, names]) => `import { ${Object.entries(names)
-            .map(([name, alias]) => `${name} as ${alias}`)
-            .join(", ")} } from '${source}';`)
-            .join("\n");
+        return [
+            ...[...imports.entries()].map(([source, names]) => `import { ${Object.entries(names)
+                .map(([name, alias]) => `${name} as ${alias}`)
+                .join(", ")} } from '${source}';`),
+            ...[...namespaceImports.entries()].map(([source, alias]) => `import * as ${alias} from '${source}';`)
+        ].join("\n");
     };
     return {
         addNamedImport,
+        addNamespaceImport,
         getImportStatements
     };
 }

package/dist/vite/types.d.ts

@@ -7,4 +7,6 @@ import type { RouteTreeEntry } from "../tree.ts";
  */
 export declare function serializeTypes(moduleId: string, routes: readonly RouteManifestEntry[], pageRoutes: readonly RouteTreeEntry[], 
 /** Directory the declaration is written to; module specifiers are relative to it. */
-from: string): string;
+from: string, 
+/** Whether lazy refs are delivered code-split (the default) or eagerly. */
+codeSplitting?: boolean): string;

package/dist/vite/types.js

@@ -23,6 +23,8 @@ const REF_TYPES = `  /** A code-split ref: the delivery adapter emits it as a dy
 
   /** An eager ref: its picked exports are imported statically. */
   export interface FileRouteEagerRef<M = Record<string, unknown>> {
+    /** The source module path — present when the convention emitted the ref lazy and \`codeSplitting: false\` delivered it eagerly. */
+    src?: string;
     require(): M;
   }
 
@@ -30,7 +32,7 @@ const REF_TYPES = `  /** A code-split ref: the delivery adapter emits it as a dy
   export interface FileRouteEntry {
     path: string;
     page?: boolean;
-    $component?: FileRouteLazyRef<any>;
+    $component?: FileRouteLazyRef<any> | FileRouteEagerRef<any>;
     $$route?: FileRouteEagerRef<any>;
     [key: string]: unknown;
   }
@@ -64,7 +66,7 @@ const isEagerRefKey = (key) => key.startsWith("$$");
  * types intact. Absent refs are typed `?: undefined` rather than omitted, so
  * an adapter can read `entry.$$route` uniformly across the tuple.
  */
-function entryType(entry, indent, nested, from) {
+function entryType(entry, indent, nested, from, codeSplitting) {
     const inner = indent + "  ";
     const fields = [`path: ${JSON.stringify(entry.path)}`];
     if (nested)
@@ -74,7 +76,9 @@ function entryType(entry, indent, nested, from) {
     // so go by the value, not the key.
     const refKeys = Object.keys(entry).filter(key => key.startsWith("$") && entry[key] !== undefined);
     for (const key of refKeys) {
-        const kind = isEagerRefKey(key) ? "eager" : "lazy";
+        // With code splitting off, the delivery adapter materializes lazy refs
+        // eagerly, so the declaration describes them as delivered.
+        const kind = isEagerRefKey(key) || !codeSplitting ? "eager" : "lazy";
         fields.push(`${key}: ${refType(entry[key], kind, from)}`);
     }
     // Reading an absent ref is how adapters branch, so keep the key present.
@@ -85,17 +89,17 @@ function entryType(entry, indent, nested, from) {
     if (nested) {
         const children = entry.children;
         fields.push(children?.length
-            ? `children: ${tupleType(children, inner, true, from)}`
+            ? `children: ${tupleType(children, inner, true, from, codeSplitting)}`
             : `children?: undefined`);
     }
     return `{\n${fields.map(field => `${inner}${field};`).join("\n")}\n${indent}}`;
 }
-function tupleType(entries, indent, nested, from) {
+function tupleType(entries, indent, nested, from, codeSplitting) {
     if (!entries.length)
         return "readonly []";
     const inner = indent + "  ";
     const members = entries
-        .map(entry => `${inner}${entryType(entry, inner, nested, from)}`)
+        .map(entry => `${inner}${entryType(entry, inner, nested, from, codeSplitting)}`)
         .join(",\n");
     return `readonly [\n${members}\n${indent}]`;
 }
@@ -106,18 +110,20 @@ function tupleType(entries, indent, nested, from) {
  */
 export function serializeTypes(moduleId, routes, pageRoutes, 
 /** Directory the declaration is written to; module specifiers are relative to it. */
-from) {
+from, 
+/** Whether lazy refs are delivered code-split (the default) or eagerly. */
+codeSplitting = true) {
     return `${HEADER}
 
 declare module ${JSON.stringify(moduleId)} {
 ${REF_TYPES}
 
   /** The flat route manifest, in scan order. */
-  const routes: ${tupleType(routes, "  ", false, from)};
+  const routes: ${tupleType(routes, "  ", false, from, codeSplitting)};
   export default routes;
 
   /** The page entries, nested by path with grouping segments stripped. */
-  export const pageRoutes: ${tupleType(pageRoutes, "  ", true, from)};
+  export const pageRoutes: ${tupleType(pageRoutes, "  ", true, from, codeSplitting)};
 }
 `;
 }

package/package.json

@@ -2,7 +2,7 @@
   "name": "filesystem-routing",
   "description": "Router-neutral file-system routing: scans a route directory into a neutral route manifest with pluggable conventions and delivery adapters",
   "license": "MIT",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "author": "Ryan Carniato",
   "homepage": "https://github.com/solidjs/filesystem-routing#readme",
   "repository": {
@@ -63,15 +63,20 @@
     "radix3": "^1.1.2"
   },
   "peerDependencies": {
+    "@tsrx/oxc": ">=0.9.0",
     "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
   },
   "peerDependenciesMeta": {
+    "@tsrx/oxc": {
+      "optional": true
+    },
     "vite": {
       "optional": true
     }
   },
   "devDependencies": {
     "@changesets/cli": "^2.31.1",
+    "@tsrx/oxc": "^0.9.0",
     "@types/node": "^22.10.0",
     "prettier": "^3.4.1",
     "typescript": "^5.7.2",

package/types.d.ts

@@ -22,6 +22,8 @@ declare module "virtual:file-routes" {
 
   /** An eager ref: its picked exports are imported statically. */
   export interface FileRouteEagerRef {
+    /** The source module path — present when the convention emitted the ref lazy and `codeSplitting: false` delivered it eagerly. */
+    src?: string;
     require(): Record<string, unknown>;
   }
 
@@ -34,8 +36,8 @@ declare module "virtual:file-routes" {
     path: string;
     /** `true` when the module renders a page. */
     page?: boolean;
-    /** The page component module. */
-    $component?: FileRouteLazyRef;
+    /** The page component module: code-split by default, an eager ref under `codeSplitting: false`. */
+    $component?: FileRouteLazyRef | FileRouteEagerRef;
     /** The route config (`route` export), when the module has one. */
     $$route?: FileRouteEagerRef;
     /** Refs added by convention extensions, e.g. `$GET` handlers. */