hono-fsr

File system router for the Hono web framework.

Features

• Zero-overhead: All file system operations happen once at initialization.
• Convention-based: Intuitive file and folder naming conventions.
• Bundlers: Support for Vite, Esbuild, and more.

Installation

# npm
npm install hono-fsr
# pnpm
pnpm add hono-fsr
# yarn
yarn add hono-fsr
# bun
bun add hono-fsr

hono-fsr is an ESM-only package.

Usage

Create Your Routes

Create a routes directory and start adding your endpoint files. The file and folder names will map directly to your URL structure.

Core Principles

• HTTP Methods: To handle a specific HTTP method, export a constant with the method's name in all uppercase (e.g., export const GET, export const POST).
• Default Export: For convenience, a default export will automatically be treated as a GET request.
• createRoute(): All handlers must be wrapped in the createRoute function. This function can accept multiple arguments, including any Hono middleware (like zValidator) followed by your final handler function.

Example

import { createRoute } from "hono-fsr";
import { zValidator } from "@hono/zod-validator";
import { z } from "zod";

// Default exports are treated as GET methods
export default createRoute((c) => {
  return c.json([
    { id: 1, title: "First Post" },
    { id: 2, title: "Second Post" },
  ]);
});

const postSchema = z.object({
  title: z.string().min(1),
  body: z.string().min(1),
});

// POST method
export const POST = createRoute(zValidator("json", postSchema), (c) => {
  // c.req.valid("json") is now typed
  const newPost = c.req.valid("json");
  return c.json({ success: true, post: newPost }, 201);
});

Initialize the Router

In your main server file, import createRouter and connect it to your Hono app.

/index.ts

import { Hono } from "hono";
import { serve } from "@hono/node-server";

// The function required to initialize the router
import { createRouter } from "hono-fsr";

import path from "node:path";
import { fileURLToPath } from "node:url";

const __dirname = path.dirname(fileURLToPath(import.meta.url));

const app = new Hono();

// Initializes the router at ./routes
await createRouter(app, {
  root: path.join(__dirname, "routes"),
});

serve(
  {
    fetch: app.fetch,
    port: 3000,
  },
  (info) => {
    console.log(
      `Server is running on port ${info.port}. (http://localhost:${info.port})`
    );
  }
);

Routing Conventions

hono-fsr uses a simple and powerful file-naming convention.

| File Name | URL Path | Example | | ------------------ | ------------ | ----------------------------------------------------------- | | index.ts | / | routes/index.ts → / | | users.ts | /users | routes/users.ts → /users | | users/index.ts | /users | routes/users/index.ts → /users | | [id].ts | /:id | routes/users/[id].ts → /users/:id | | [[id]].ts | /:id? | routes/optional/[[id]].ts → /optional/:id? | | [...path].ts | /* | routes/files/[...path].ts → /files/* | | (group)/about.ts | /about | routes/(marketing)/about.ts → /about | | +middleware.ts | (Middleware) | Applies to all routes in its directory and sub-directories. | | _filename.ts | (Ignored) | Files that start with an underscore are ignored. |

Configuration

The createRouter function accepts an options object to customize its behavior.

| Option | Description | Type | Default | | --------------- | --------------------------------------------------------------------------- | ----------------------------------- | ------------ | | root | The root directory of the routes. | string | Required | | manifest | The path to the generated manifest file. | Manifest | undefined | | debug | Enable verbose logging for debugging. | boolean | false | | rpc | Allows sharing of the API specifications between the server and the client. | boolean | false | | basePath | A path prefix for all routes. | string | / | | trailingSlash | Defines the trailing slash behavior for all routes. | "always" \| "never" \| "preserve" | "preserve" |

Read more about how to use the manifest option in the Bundlers section of the Wiki.

Example Configuration

createRouter(app, {
  root: path.join(__dirname, "routes"),
  debug: process.env.NODE_ENV !== "production",
  rpc: true,
  basePath: "/api/v1",
  trailingSlash: "never",
});

Alternatives

For projects that require tight integration between a frontend (React) and backend, or a full-stack experience, consider using honox. It is a full meta-framework that also supports file system routing and server-side rendering with React.

hono-fsr is a powerful and lean server-side routing layer. Its sole focus is to provide a robust, convention-driven foundation for organizing your application's endpoints. It remains completely unopinionated about what your handlers return, be it JSON for an API, or HTML from Hono's built-in JSX renderer for a server-rendered site.

Documentation

This README provides a quickstart and reference for the main features. For detailed guides on all conventions, configuration options, and advanced topics, please visit the Wiki.

License

hono-fsr is under the MIT license.