filesystem-routing 0.1.1 → 0.2.1

package/README.md

@@ -13,8 +13,8 @@ a delivery adapter that materializes the manifest into code.
 | Scanning, filename convention, neutral route manifest | `filesystem-routing` |
 | Nesting + `(group)` stripping | `filesystem-routing/tree` |
 | Vite delivery (virtual module, HMR, code splitting, build inputs) | `filesystem-routing/vite` |
-| `RouteDefinition` emission | `@solidjs/router/fs` |
-| Request handling for `GET`/`POST` routes, middleware | `@solidjs/start` |
+| Request dispatch for `GET`/`POST` routes, as fetch middleware | `filesystem-routing/api` |
+| `RouteDefinition` emission for Solid Router (code splitting, typed paths) | `@solidjs/router/fs` |
 
 Nothing here is Solid-specific: the core is bundler-agnostic — it never imports
 Vite — the Vite adapter is router-agnostic, and the conventions are the ones
@@ -47,9 +47,11 @@ const Router = createRouter({ routes: fileRoutes(pageRoutes) });
 export const App = () => <Router>{props => <>{props.children}</>}</Router>;
 ```
 
-The emission adapter never imports the virtual module itself — the app does,
-so the adapter resolves without the plugin, custom `moduleId`s work, and
-nothing needs excluding from dependency prebundling.
+The emission adapter ships with the router — `@solidjs/router/fs` for Solid
+Router; other routers mirror the same shape in their own packages. It never
+imports a virtual module itself — the app does, so the adapter resolves
+without the plugin, custom `moduleId`s work, and nothing needs excluding
+from dependency prebundling.
 
 Route modules live in `src/routes` (configurable via `fileRoutes({ dir })`).
 A module is a page when it has a default export, and may export a `route`
@@ -161,25 +163,29 @@ pages get:
 - The recognized set is `HEAD`/`GET`/`POST`/`PUT`/`DELETE`/`PATCH`/`OPTIONS`;
   pass an array instead of `true` to change it.
 
-This package stops at the manifest: it discovers handlers, it does not serve
-them. Dispatch is a few lines in whatever server consumes the manifest —
-match the URL, import the ref, call the export:
+Dispatch ships as fetch-style middleware — `filesystem-routing/api` matches
+requests against the manifest's handler refs and composes into any
+`(request, next)` chain, an SSR handler's middleware option included:
 
 ```ts
-// any SSR handler or middleware
+// src/middleware.ts
 import routes from "virtual:file-routes";
+import { createAPIHandler } from "filesystem-routing/api";
 
-async function handleApi(request: Request, entry, params) {
-  const ref = entry[`$${request.method}`];
-  if (!ref) return new Response(null, { status: 405 });
-  const handlers = await ref.import();
-  // a HEAD alias imports the GET handler
-  return (handlers[request.method] ?? handlers.GET)({ request, params });
-}
+export default [createAPIHandler(routes)];
 ```
 
-The handler's argument is whatever your server passes — the convention only
-dictates the export names. Frameworks typically enable `httpMethods` on the
+Handlers receive the request event of the surrounding scope (the storage
+`provideRequestEvent` establishes — pass `getEvent` to dispatch outside
+one), with the matched `params` written onto it. Unmatched requests (no
+route, or no handler for the method) advance the chain; `HEAD` falls back
+to the `GET` handler; returned strings and JSON values are coerced into
+responses. A `GET` handler may decline by returning `undefined`: a module
+that is also a page falls through to the chain (its component renders
+instead), a handler-only module answers 404. `createAPIMatcher` exposes the
+matching alone for servers with their own dispatch shape.
+
+Frameworks typically enable `httpMethods` on the
 server environment's router only (SolidStart pairs it with `components:
 false` in SPA mode, so the server manifest routes requests without shipping
 page modules) — see the per-environment `routers` option below.
@@ -235,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";
@@ -247,10 +259,10 @@ with `(group)` segments stripped, so emission adapters don't each reimplement
 the tree (`buildRouteTree` from `filesystem-routing/tree` is the same
 function, for consumers holding only a flat manifest). An emission adapter is
 a function taking manifest entries and returning the router's shape — see
-`fileRoutes` in `@solidjs/router/fs` for Solid Router's, a ~30 line adapter
-other routers can mirror. Adapters take the manifest as an argument rather
-than importing the virtual module, so they work standalone and with custom
-module ids.
+`fileRoutes` in `@solidjs/router/fs` for Solid Router's, an
+adapter other routers can mirror. Adapters take the manifest as an argument
+rather than importing the virtual module, so they work standalone and with
+custom module ids.
 
 Add `/// <reference types="filesystem-routing/types" />` to type the import.
 
@@ -299,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/api.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The API dispatch adapter: matches requests against the flat manifest's
+ * handler refs (`$GET`, `$POST`, …) and serves them as fetch-style
+ * middleware, so API routes compose into any `(request, next)` chain — an
+ * SSR handler's middleware option, a framework's request pipeline — with no
+ * bundler or server involvement.
+ *
+ * Ported from SolidStart's `server/routes.ts` (the radix3 matcher) and the
+ * method dispatch in its `server/handler.ts`.
+ */
+/**
+ * The event a handler receives. Structurally the core request event —
+ * `getRequestEvent()` inside the handler sees the same object — with the
+ * matched route params written onto it before dispatch.
+ */
+export interface APIEvent {
+    request: Request;
+    params?: Record<string, string>;
+    [key: string]: unknown;
+}
+/**
+ * An API handler: an uppercase method export of a route module. Return a
+ * `Response` to answer the request; strings and JSON values are coerced
+ * (`new Response(text)` / `Response.json(value)`). A `GET` handler may
+ * return `undefined` to decline, falling through to the rest of the chain
+ * when the module is also a page.
+ */
+export type APIHandler = (event: APIEvent) => unknown;
+/** A manifest entry as the delivery adapter serves it. */
+export interface FileRouteHandlers {
+    path: string;
+    page?: boolean;
+    $component?: unknown;
+    $HEAD?: APIHandlerRef;
+    $GET?: APIHandlerRef;
+    $POST?: APIHandlerRef;
+    $PUT?: APIHandlerRef;
+    $PATCH?: APIHandlerRef;
+    $DELETE?: APIHandlerRef;
+    [key: string]: unknown;
+}
+/**
+ * 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>;
+    /** `true` when the module also renders a page at this path. */
+    isPage: boolean;
+}
+/**
+ * Builds a matcher over the flat manifest's handler-carrying entries. Route
+ * paths translate from the neutral pattern language to the radix tree —
+ * `(group)` segments stripped, `*rest` catch-alls, static segments
+ * URL-encoded. Optional parameters are rejected (a radix tree cannot
+ * represent them) and duplicate paths are a configuration error.
+ */
+export declare function createAPIMatcher(routes: readonly FileRouteHandlers[]): (path: string, method: string) => APIMatch | undefined;
+/** Strips a leading path base: `stripPathBase("/app/x", "/app")` → `/x`. */
+export declare function stripPathBase(path: string, base: string): string;
+export interface APIHandlerOptions {
+    /** A path base stripped from the URL before matching. Defaults to `/`. */
+    base?: string;
+    /**
+     * How the adapter reaches the request event it hands to handlers. Defaults
+     * to the core request-event scope (the storage `provideRequestEvent`
+     * establishes), which is where a middleware chain runs — override it when
+     * dispatching outside one, or to hand handlers a richer event.
+     */
+    getEvent?: () => APIEvent;
+}
+/**
+ * Fetch-style middleware serving the manifest's API routes:
+ *
+ * ```ts
+ * import routes from "virtual:file-routes";
+ * import { createAPIHandler } from "filesystem-routing/api";
+ *
+ * export default [createAPIHandler(routes)];
+ * ```
+ *
+ * Dispatch preserves SolidStart's semantics: unmatched requests (no route,
+ * or no handler for the method) advance the chain; `HEAD` falls back to the
+ * `GET` handler; matched params are written to `event.params` before the
+ * handler runs. A handler returning `undefined` declines the request —
+ * allowed for `GET` only (anything else throws): a page module falls
+ * through to the chain (its component renders instead), a handler-only
+ * module answers 404.
+ */
+export declare function createAPIHandler(routes: readonly FileRouteHandlers[], options?: APIHandlerOptions): (request: Request, next: (request?: Request) => Response | Promise<Response>) => Promise<Response>;

package/dist/api.js

@@ -0,0 +1,120 @@
+import { createRouter } from "radix3";
+function containsHTTP(route) {
+    return route.$HEAD || route.$GET || route.$POST || route.$PUT || route.$PATCH || route.$DELETE;
+}
+/**
+ * Builds a matcher over the flat manifest's handler-carrying entries. Route
+ * paths translate from the neutral pattern language to the radix tree —
+ * `(group)` segments stripped, `*rest` catch-alls, static segments
+ * URL-encoded. Optional parameters are rejected (a radix tree cannot
+ * represent them) and duplicate paths are a configuration error.
+ */
+export function createAPIMatcher(routes) {
+    const router = createRouter({
+        routes: routes.reduce((memo, route) => {
+            if (!containsHTTP(route))
+                return memo;
+            const path = route.path
+                .replace(/\([^)/]+\)/g, "")
+                .replace(/\/+/g, "/")
+                .replace(/\*([^/]*)/g, (_, m) => `**:${m}`)
+                .split("/")
+                .map(s => (s.startsWith(":") || s.startsWith("*") ? s : encodeURIComponent(s)))
+                .join("/");
+            if (/:[^/]*\?/g.test(path)) {
+                throw new Error(`Optional parameters are not supported in API routes: ${path}`);
+            }
+            if (memo[path]) {
+                throw new Error(`Duplicate API routes for "${path}" found at "${memo[path].route.path}" and "${route.path}"`);
+            }
+            memo[path] = { route };
+            return memo;
+        }, {})
+    });
+    return (path, method) => {
+        const match = router.lookup(path);
+        if (!match || !match.route)
+            return;
+        const route = match.route;
+        // A `GET` handler answers `HEAD` unless the module handles it itself.
+        const handler = method === "HEAD" ? route.$HEAD || route.$GET : route[`$${method}`];
+        if (handler === undefined)
+            return;
+        return {
+            handler: handler,
+            params: match.params,
+            isPage: route.page === true && route.$component !== undefined
+        };
+    };
+}
+/** Strips a leading path base: `stripPathBase("/app/x", "/app")` → `/x`. */
+export function stripPathBase(path, base) {
+    if (!base || base === "/")
+        return path;
+    const normalizedBase = base.endsWith("/") ? base.slice(0, -1) : base;
+    if (path === normalizedBase)
+        return "/";
+    if (path.startsWith(`${normalizedBase}/`))
+        return path.slice(normalizedBase.length);
+    return path;
+}
+const RequestContext = Symbol.for("solid.RequestContext");
+function getScopedEvent() {
+    const event = globalThis[RequestContext]?.getStore();
+    if (!event) {
+        throw new Error("API route dispatched outside a request-event scope. Compose the handler " +
+            "inside `provideRequestEvent` (any `ssr.middleware`-style chain already is), " +
+            "or pass `getEvent`.");
+    }
+    return event;
+}
+function toResponse(result) {
+    if (result instanceof Response)
+        return result;
+    if (typeof result === "string")
+        return new Response(result);
+    return Response.json(result);
+}
+/**
+ * Fetch-style middleware serving the manifest's API routes:
+ *
+ * ```ts
+ * import routes from "virtual:file-routes";
+ * import { createAPIHandler } from "filesystem-routing/api";
+ *
+ * export default [createAPIHandler(routes)];
+ * ```
+ *
+ * Dispatch preserves SolidStart's semantics: unmatched requests (no route,
+ * or no handler for the method) advance the chain; `HEAD` falls back to the
+ * `GET` handler; matched params are written to `event.params` before the
+ * handler runs. A handler returning `undefined` declines the request —
+ * allowed for `GET` only (anything else throws): a page module falls
+ * through to the chain (its component renders instead), a handler-only
+ * module answers 404.
+ */
+export function createAPIHandler(routes, options = {}) {
+    const match = createAPIMatcher(routes);
+    const getEvent = options.getEvent ?? getScopedEvent;
+    return async (request, next) => {
+        const url = new URL(request.url);
+        const matched = match(stripPathBase(url.pathname, options.base ?? "/"), request.method);
+        if (!matched)
+            return next();
+        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();
+        const event = getEvent();
+        event.params = matched.params || {};
+        const result = await fn(event);
+        if (result !== undefined)
+            return toResponse(result);
+        if (request.method !== "GET") {
+            throw new Error(`API handler for ${request.method} "${request.url}" did not return a response.`);
+        }
+        if (!matched.isPage)
+            return new Response(null, { status: 404 });
+        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/index.d.ts

@@ -3,7 +3,7 @@ import { type PageFileSystemRouterConfig } from "../convention.ts";
 import { BaseFileSystemRouter } from "../router.ts";
 import { DEFAULT_EXTENSIONS, moduleId } from "./constants.ts";
 export { DEFAULT_EXTENSIONS, moduleId };
-export { treeShake } from "./tree-shake.ts";
+export { sanitizeChunkFileName, toPickId, treeShake } from "./tree-shake.ts";
 export { fileSystemWatcher } from "./fs-watcher.ts";
 export interface FileRoutesOptions extends Pick<PageFileSystemRouterConfig, "components" | "httpMethods" | "toPath" | "toRoute"> {
     /** Route directory, relative to the Vite root. Defaults to `src/routes`. */
@@ -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

@@ -5,11 +5,50 @@ import { normalizePath } from "../router.js";
 import { buildRouteTree } from "../tree.js";
 import { DEFAULT_EXTENSIONS, moduleId } from "./constants.js";
 import { fileSystemWatcher } from "./fs-watcher.js";
-import { treeShake } from "./tree-shake.js";
+import { sanitizeChunkFileName, toPickId, treeShake } from "./tree-shake.js";
 import { serializeTypes } from "./types.js";
 export { DEFAULT_EXTENSIONS, moduleId };
-export { treeShake } from "./tree-shake.js";
+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;
@@ -61,20 +107,27 @@ export function fileRoutes(options = {}) {
         writeFileSync(file, contents);
     }
     /** The id a route module ref is loaded from: its source plus its picks. */
-    const toModuleId = (ref) => `${ref.src}?${ref.pick.map(pick => `pick=${pick}`).join("&")}`;
+    const toModuleId = (ref) => toPickId(ref.src, ref.pick);
     return [
         {
             name: "filesystem-routing",
             enforce: "pre",
             config() {
-                // Packages importing the virtual module (which only this plugin can
-                // resolve) must stay out of esbuild prebundling.
-                if (!options.optimizeDepsExclude?.length)
-                    return;
                 return {
-                    optimizeDeps: {
-                        exclude: options.optimizeDepsExclude
-                    }
+                    build: {
+                        rollupOptions: {
+                            output: {
+                                // Keeps route chunks named after their file rather than after
+                                // the `?pick=...` id that addresses them. See toPickId.
+                                sanitizeFileName: sanitizeChunkFileName
+                            }
+                        }
+                    },
+                    // Packages importing the virtual module (which only this plugin can
+                    // resolve) must stay out of esbuild prebundling.
+                    ...(options.optimizeDepsExclude?.length
+                        ? { optimizeDeps: { exclude: options.optimizeDepsExclude } }
+                        : {})
                 };
             },
             configResolved(config) {
@@ -94,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));
@@ -124,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;
@@ -143,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,
@@ -185,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);
@@ -201,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/tree-shake.d.ts

@@ -1,2 +1,29 @@
 import type { Plugin } from "vite";
+/**
+ * Builds the module id used to import a subset of a route file's exports.
+ *
+ * The `pick` list has to live in the query so that the same file can be
+ * instantiated once per export subset (the client picks `default`/`$css`,
+ * the server picks its HTTP handlers). That query would otherwise leave the
+ * id ending in `?pick=GET`, which silently excludes route files from any
+ * plugin whose filter is anchored on the file extension -- a very common
+ * default, e.g. unplugin-macros' `/\.[cm]?[jt]sx?$/`.
+ *
+ * The trailing `lang.<ext>` marker is the same convention Vue SFCs use
+ * (`?vue&type=script&lang.ts`) and puts a real extension back at the end of
+ * the id, so those filters match again.
+ *
+ * @see https://github.com/solidjs/solid-start/issues/1918
+ */
+export declare function toPickId(src: string, pick: string[]): string;
+/**
+ * Rollup's default chunk name sanitizer, plus a pass that drops the
+ * `?pick=...&lang` tail so route chunks keep the short, stable filenames they
+ * had before the `lang` marker was introduced (`index-<hash>.js`, not
+ * `index.tsx_pick_default_pick__css_lang-<hash>.js`). Client chunk filenames
+ * are public URLs, so this is not purely cosmetic.
+ *
+ * @see https://github.com/rollup/rollup/blob/master/src/utils/sanitizeFileName.ts
+ */
+export declare function sanitizeChunkFileName(name: string): string;
 export declare function treeShake(): Plugin;

package/dist/vite/tree-shake.js

@@ -1,7 +1,52 @@
 // All credit for this work goes to the amazing Next.js team.
 // https://github.com/vercel/next.js/blob/canary/packages/next/build/babel/plugins/next-ssg-transform.ts
 // This is adapted to work with routeData functions. It can be run in two modes, one which preserves the routeData and the Component in the same file, and one which creates a
-import { basename } from "node:path";
+import { basename, extname } from "node:path";
+const PICKABLE_EXTENSIONS = ["js", "jsx", "ts", "tsx"];
+/**
+ * Builds the module id used to import a subset of a route file's exports.
+ *
+ * The `pick` list has to live in the query so that the same file can be
+ * instantiated once per export subset (the client picks `default`/`$css`,
+ * the server picks its HTTP handlers). That query would otherwise leave the
+ * id ending in `?pick=GET`, which silently excludes route files from any
+ * plugin whose filter is anchored on the file extension -- a very common
+ * default, e.g. unplugin-macros' `/\.[cm]?[jt]sx?$/`.
+ *
+ * The trailing `lang.<ext>` marker is the same convention Vue SFCs use
+ * (`?vue&type=script&lang.ts`) and puts a real extension back at the end of
+ * the id, so those filters match again.
+ *
+ * @see https://github.com/solidjs/solid-start/issues/1918
+ */
+export function toPickId(src, pick) {
+    const query = pick.map(p => `pick=${p}`).join("&");
+    const ext = extname(src).slice(1);
+    return PICKABLE_EXTENSIONS.includes(ext) ? `${src}?${query}&lang.${ext}` : `${src}?${query}`;
+}
+/**
+ * Matches the tail that {@link toPickId} appends, as it appears in a chunk
+ * name. Bundlers derive a chunk name from the module id by taking the
+ * basename minus its extension, so `index.tsx?pick=default&pick=$css&lang.tsx`
+ * arrives here as `index.tsx?pick=default&pick=$css&lang`.
+ */
+const PICK_CHUNK_NAME_RE = /\.[cm]?[jt]sx?\?pick=[^?]*&lang$/;
+const INVALID_CHAR_RE = /[\u0000-\u001F"#$&*+,:;<=>?[\]^`{|}\u007F]/g;
+const DRIVE_LETTER_RE = /^[a-z]:/i;
+/**
+ * Rollup's default chunk name sanitizer, plus a pass that drops the
+ * `?pick=...&lang` tail so route chunks keep the short, stable filenames they
+ * had before the `lang` marker was introduced (`index-<hash>.js`, not
+ * `index.tsx_pick_default_pick__css_lang-<hash>.js`). Client chunk filenames
+ * are public URLs, so this is not purely cosmetic.
+ *
+ * @see https://github.com/rollup/rollup/blob/master/src/utils/sanitizeFileName.ts
+ */
+export function sanitizeChunkFileName(name) {
+    const stripped = name.replace(PICK_CHUNK_NAME_RE, "");
+    const driveLetter = DRIVE_LETTER_RE.exec(stripped)?.[0] ?? "";
+    return driveLetter + stripped.slice(driveLetter.length).replace(INVALID_CHAR_RE, "_");
+}
 function treeShakeTransform({ types: t }) {
     function getIdentifier(path) {
         const parentPath = path.parentPath;
@@ -133,6 +178,11 @@ function treeShakeTransform({ types: t }) {
                             if (!state.opts.pick) {
                                 return;
                             }
+                            // Only module-level exports are route exports; `export` inside a
+                            // TS namespace/module block is unrelated to the pick list.
+                            if (!exportNamedPath.parentPath.isProgram()) {
+                                return;
+                            }
                             const specifiers = exportNamedPath.get("specifiers");
                             if (specifiers.length) {
                                 specifiers.forEach(s => {

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.1.1",
+  "version": "0.2.1",
   "author": "Ryan Carniato",
   "homepage": "https://github.com/solidjs/filesystem-routing#readme",
   "repository": {
@@ -40,6 +40,10 @@
       "types": "./dist/vite/index.d.ts",
       "default": "./dist/vite/index.js"
     },
+    "./api": {
+      "types": "./dist/api.d.ts",
+      "default": "./dist/api.js"
+    },
     "./types": {
       "types": "./types.d.ts"
     }
@@ -55,7 +59,8 @@
     "@types/micromatch": "^4.0.10",
     "fast-glob": "^3.3.3",
     "micromatch": "^4.0.8",
-    "oxc-parser": "^0.139.0"
+    "oxc-parser": "^0.139.0",
+    "radix3": "^1.1.2"
   },
   "peerDependencies": {
     "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"

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. */