{"id":29564546,"url":"https://github.com/itsbrunodev/hono-fsr","last_synced_at":"2026-01-20T17:35:24.216Z","repository":{"id":304877356,"uuid":"1020385528","full_name":"itsbrunodev/hono-fsr","owner":"itsbrunodev","description":"File-system router for the Hono web framework.","archived":false,"fork":false,"pushed_at":"2025-07-16T12:24:51.000Z","size":129,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-16T17:52:28.533Z","etag":null,"topics":["api","backend","file-system","file-system-routing","framework","fs-router","hono","router","server","web"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/hono-fsr","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/itsbrunodev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-15T19:33:58.000Z","updated_at":"2025-07-16T12:24:55.000Z","dependencies_parsed_at":"2025-07-16T23:39:44.512Z","dependency_job_id":"b5fb2b24-b807-4774-a0eb-54135b8611c0","html_url":"https://github.com/itsbrunodev/hono-fsr","commit_stats":null,"previous_names":["itsbrunodev/hono-fsr"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/itsbrunodev/hono-fsr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsbrunodev%2Fhono-fsr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsbrunodev%2Fhono-fsr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsbrunodev%2Fhono-fsr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsbrunodev%2Fhono-fsr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/itsbrunodev","download_url":"https://codeload.github.com/itsbrunodev/hono-fsr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsbrunodev%2Fhono-fsr/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265653923,"owners_count":23805888,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","backend","file-system","file-system-routing","framework","fs-router","hono","router","server","web"],"created_at":"2025-07-18T20:01:11.956Z","updated_at":"2026-01-20T17:35:24.210Z","avatar_url":"https://github.com/itsbrunodev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hono-fsr\n\nFile system router for the [Hono](https://hono.dev) web framework.\n\n## Features\n\n- **Zero-overhead**: All file system operations happen once at initialization.\n- **Convention-based**: Intuitive file and folder naming conventions.\n- **Bundlers**: Support for Vite, Esbuild, and more.\n\n## Installation\n\n```bash\n# npm\nnpm install hono-fsr\n# pnpm\npnpm add hono-fsr\n# yarn\nyarn add hono-fsr\n# bun\nbun add hono-fsr\n```\n\n\u003e hono-fsr is an **ESM-only** package.\n\n## Usage\n\n### Create Your Routes\n\nCreate a `routes` directory and start adding your endpoint files. The file and folder names will map directly to your URL structure.\n\n#### Core Principles\n\n- **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`).\n- **Default Export**: For convenience, a default export will automatically be treated as a GET request.\n- **`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.\n\n#### Example\n\n```typescript\nimport { createRoute } from \"hono-fsr\";\nimport { zValidator } from \"@hono/zod-validator\";\nimport { z } from \"zod\";\n\n// Default exports are treated as GET methods\nexport default createRoute((c) =\u003e {\n  return c.json([\n    { id: 1, title: \"First Post\" },\n    { id: 2, title: \"Second Post\" },\n  ]);\n});\n\nconst postSchema = z.object({\n  title: z.string().min(1),\n  body: z.string().min(1),\n});\n\n// POST method\nexport const POST = createRoute(zValidator(\"json\", postSchema), (c) =\u003e {\n  // c.req.valid(\"json\") is now typed\n  const newPost = c.req.valid(\"json\");\n  return c.json({ success: true, post: newPost }, 201);\n});\n```\n\n### Initialize the Router\n\nIn your main server file, import `createRouter` and connect it to your Hono app.\n\n#### `/index.ts`\n\n```typescript\nimport { Hono } from \"hono\";\nimport { serve } from \"@hono/node-server\";\n\n// The function required to initialize the router\nimport { createRouter } from \"hono-fsr\";\n\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\nconst __dirname = path.dirname(fileURLToPath(import.meta.url));\n\nconst app = new Hono();\n\n// Initializes the router at ./routes\nawait createRouter(app, {\n  root: path.join(__dirname, \"routes\"),\n});\n\nserve(\n  {\n    fetch: app.fetch,\n    port: 3000,\n  },\n  (info) =\u003e {\n    console.log(\n      `Server is running on port ${info.port}. (http://localhost:${info.port})`\n    );\n  }\n);\n```\n\n## Routing Conventions\n\nhono-fsr uses a simple and powerful file-naming convention.\n\n| File Name          | URL Path     | Example                                                     |\n| ------------------ | ------------ | ----------------------------------------------------------- |\n| `index.ts`         | `/`          | `routes/index.ts` → `/`                                     |\n| `users.ts`         | `/users`     | `routes/users.ts` → `/users`                                |\n| `users/index.ts`   | `/users`     | `routes/users/index.ts` → `/users`                          |\n| `[id].ts`          | `/:id`       | `routes/users/[id].ts` → `/users/:id`                       |\n| `[[id]].ts`        | `/:id?`      | `routes/optional/[[id]].ts` → `/optional/:id?`              |\n| `[...path].ts`     | `/*`         | `routes/files/[...path].ts` → `/files/*`                    |\n| `(group)/about.ts` | `/about`     | `routes/(marketing)/about.ts` → `/about`                    |\n| `+middleware.ts`   | (Middleware) | Applies to all routes in its directory and sub-directories. |\n| `_filename.ts`     | (Ignored)    | Files that start with an underscore are ignored.            |\n\n## Configuration\n\nThe `createRouter` function accepts an options object to customize its behavior.\n\n| Option          | Description                                                                 | Type                                | Default      |\n| --------------- | --------------------------------------------------------------------------- | ----------------------------------- | ------------ |\n| `root`          | The root directory of the routes.                                           | `string`                            | **Required** |\n| `manifest`      | The path to the generated manifest file.                                    | `Manifest`                          | `undefined`  |\n| `debug`         | Enable verbose logging for debugging.                                       | `boolean`                           | `false`      |\n| `rpc`           | Allows sharing of the API specifications between the server and the client. | `boolean`                           | `false`      |\n| `basePath`      | A path prefix for all routes.                                               | `string`                            | `/`          |\n| `trailingSlash` | Defines the trailing slash behavior for all routes.                         | `\"always\" \\| \"never\" \\| \"preserve\"` | `\"preserve\"` |\n\n\u003e Read more about how to use the manifest option in the [Bundlers](https://github.com/itsbrunodev/hono-fsr/wiki/Bundlers) section of the Wiki.\n\n### Example Configuration\n\n```typescript\ncreateRouter(app, {\n  root: path.join(__dirname, \"routes\"),\n  debug: process.env.NODE_ENV !== \"production\",\n  rpc: true,\n  basePath: \"/api/v1\",\n  trailingSlash: \"never\",\n});\n```\n\n## Alternatives\n\nFor projects that require tight integration between a frontend (React) and backend, or a full-stack experience, consider using [honox](https://github.com/honojs/honox). It is a full meta-framework that also supports file system routing and server-side rendering with React.\n\nhono-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.\n\n## Documentation\n\nThis 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](https://github.com/itsbrunodev/hono-fsr/wiki).\n\n## License\n\nhono-fsr is under the [MIT](./LICENSE.md) license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitsbrunodev%2Fhono-fsr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitsbrunodev%2Fhono-fsr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitsbrunodev%2Fhono-fsr/lists"}