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

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:

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:

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:

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:

• A module with handlers but no default export routes without being a page: { path: "/api/posts/:id", page: false, $GET, $DELETE }. • A module can be both. A page with a GET export gets $component *and* $GET, and handler exports are excluded from the component ref's picks, so handler code never reaches the client bundle. • A lone GET also answers HEAD: a $HEAD ref aliasing the GET export is added unless the module exports its own. • The recognized set is HEAD/GET/POST/PUT/DELETE/PATCH/OPTIONS; pass an array instead of true to change it.

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:

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.

Server-function pages

With serverComponents: true, a page whose default export begins with a "use server" directive is a server-function page:…

Description from the npm listing.