Itty-fs-router NPM

itty-fs-router is a powerful file-system router. You can use the file-system to define routes, instead of defining them all in one place, allowing you to organize your routes in a way that makes sense for your project.

Under the hood, this tooling uses itty-router. Itty is an incredibly small and feature-rich router, with super fast performance.

Features

File-system based routing.
Middleware.
Not found handlers.
Route patterns; params, wildcards, greedy params, and more.

Support for more features is coming soon!

Getting Started

Installation

To get started with itty-fs-router, you'll first need to install it in your project.

npm install itty-fs-router

Defining Routes

To define a route, simply create a new file. The path to the file will be the path of the route. As an example, the following paths would map to following routes:

/index.ts -> /
/foo/bar.ts -> /foo/bar

Routes can be defined on a per-method basis, or for all methods using ALL.

// path: ./src/index.ts

import type { RouteHandler } from 'itty-fs-router';

// GET /
export const GET: RouteHandler = () => {
	return new Response('Hello world!', { status: 200 });
};

Route Params and Patterns

Route params can be defined using two syntaxes; the one that this library provides, or the same syntax that itty-router uses.

The syntax itty-fs-router (this library) provides is as follows. For more information, take a look at our docs.

simple params: [param]
optional params: [[param]]
wildcard: [...]
greedy params: [...param]
file extensions: [param].ext, name.[[ext]], etc.

If you would like to use itty-router's syntax to define route params, greedy params, wildcards, etc., check out the itty-router docs.

Middleware and Not Found

By default, itty-fs-router adds a global Not found response for any unmatched routes. This can be overriden on a per-route basis by exporting an object. (per-route segment and project-wide is coming soon)

Middleware and Not Found responses can be defined on a per-method basis, or for all methods using ALL.

Check out our documentation for middleware and not found for more information.

// path: ./src/index.ts

import type { Middleware, NotFound, RouteHandler } from 'itty-fs-router';

// GET /
export const GET: RouteHandler = (req) => {
	const middlewareCtx = req.ctx['from-middleware'];

	return new Response(`Middleware Context: '${middlewareCtx}'`);
};

export const middleware: Middleware = {
	// GET /
	GET: (req) => {
		req.ctx['from-middleware'] = 'Context from middleware';
	},
};

export const notFound: NotFound = {
	// POST /, PUT /, DELETE /, etc.
	ALL: () => {
		return new Response('No route handler was defined for this request method', { status: 404 });
	},
};