filesystem-routing weekly downloads statistics

filesystem-routing

Router-neutral file-system routing.

This package owns the machinery of file routing — scanning a directory, applying a filename convention and producing a neutral route manifest — while routers own the shapes: each router ships a small emission adapter that turns the manifest into its own route definitions, and each bundler ships a delivery adapter that materializes the manifest into code.

Piece	Owner
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
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 proven by SolidStart. The manifest is served from virtual:file-routes, or from whatever id you pass as fileRoutes({ moduleId }).

Usage with Solid Router and Vite

// vite.config.ts
import { fileRoutes } from "filesystem-routing/vite";
import { defineConfig } from "vite";
import solid from "vite-plugin-solid";

export default defineConfig({
  // `extensions` makes vite-plugin-solid also compile the `?pick=` route
  // modules this plugin emits (their ids end in a query string)
  plugins: [solid({ extensions: [".jsx", ".tsx"] }), fileRoutes()]
});

// src/app.tsx
import { pageRoutes } from "virtual:file-routes";
import { createRouter } from "@solidjs/router";
import { fileRoutes } from "@solidjs/router/fs";

const Router = createRouter({ routes: fileRoutes(pageRoutes) });

export const App = () => <Router>{props => <>{props.children}</>}</Router>;

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 moduleIds 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 config object:

// src/routes/blog/[id].tsx
import type { RouteDefinition } from "@solidjs/router";

export const route = {
  preload: ({ params }) => loadPost(params.id)
} satisfies RouteDefinition;

export default function Post() {
  return <h1>Post</h1>;
}

Filename conventions

Two conventions ship in the box. Both produce the same neutral manifest and share the same module convention (default export is a page, route config export, httpMethods handlers), so they are equally capable — only the filenames differ.

Nested (PageFileSystemRouter, the default)

The convention proven by SolidStart:

File	Path
index.tsx	/
about.tsx	/about
blog/[id].tsx	/blog/:id
blog/[[page]].tsx	/blog/:page?
docs/[...path].tsx	/docs/*path
(marketing)/about.tsx	/about, nested in the (marketing) group

Nested layouts come from pairing a file with a directory: blog.tsx is the layout for everything in blog/.

Flat (FlatFileSystemRouter)

The convention proven by Remix v2 and carried forward by React Router's @react-router/fs-routes — . delimiters instead of directories:

File	Path
_index.tsx	/
about.tsx	/about
concerts.trending.tsx	/concerts/trending
concerts.$city.tsx	/concerts/:city
concerts.($page).tsx	/concerts/:page?
files.$.tsx	/files/*splat
_auth.login.tsx	/login, nested in the _auth.tsx pathless layout
concerts_.mine.tsx	/concerts/mine, escaping the concerts.tsx layout
[sitemap.xml].tsx	/sitemap.xml — brackets escape special characters

concerts.tsx is the layout for every concerts.* file; a top-level folder routes through its route.tsx module and co-locates everything else in the folder without routing it. Pass the router to the plugin:

import { FlatFileSystemRouter } from "filesystem-routing";
import { fileRoutes } from "filesystem-routing/vite";
import { resolve } from "node:path";

fileRoutes({
  router: new FlatFileSystemRouter({
    dir: resolve("src/routes"),
    extensions: ["js", "jsx", "ts", "tsx"]
  })
});

Two departures from Remix: the catch-all param is named (params.splat rather than params["*"]), and optional static segments ((en).about.tsx) are rejected — the neutral pattern language has no representation for them.

API routes

Route modules can answer requests as well as render. Turn on httpMethods (off by default — a client-only manifest has no use for handlers) and uppercase exports become request handlers:

// src/routes/api/posts/[id].ts
export function GET(event) {
  return Response.json(loadPost(event.params.id));
}

export function DELETE(event) {
  deletePost(event.params.id);
  return new Response(null, { status: 204 });
}

The scanner turns each handler export into a lazy ref on the entry — $GET: { src, pick: ["GET"] }, $DELETE: … — with the same code splitting pages get:…