Simple and fast file-system based router,
powered by itty-router.
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.
- File-system based routing.
- Middleware.
- Not found handlers.
- Route patterns; params, wildcards, greedy params, and more.
Support for more features is coming soon!
To get started with itty-fs-router
, you'll first need to install it in your project.
npm install itty-fs-router
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 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.
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 });
},
};
To deploy your project, you will need to build it. This can be done by running the following in your project's directory.
npx itty-fs-router
Then, you can deploy the dist
directory (or whatever directory you specified in the CLI arguments).
For more information about CLI arguments, run the following.
npx itty-fs-router --help
Contributions are welcome! Please read our contribution guidelines for more information.