{"id":14529617,"url":"https://github.com/venables/typed-route-handler","last_synced_at":"2025-04-05T04:08:45.124Z","repository":{"id":216218442,"uuid":"740757634","full_name":"venables/typed-route-handler","owner":"venables","description":"Type-safe API Route Handlers for Next.js","archived":false,"fork":false,"pushed_at":"2024-12-13T01:08:27.000Z","size":710,"stargazers_count":88,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-29T03:04:28.217Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/venables.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2024-01-09T02:09:45.000Z","updated_at":"2025-03-18T08:29:30.000Z","dependencies_parsed_at":null,"dependency_job_id":"d6e070cb-f949-473b-b129-4d685d850179","html_url":"https://github.com/venables/typed-route-handler","commit_stats":{"total_commits":33,"total_committers":3,"mean_commits":11.0,"dds":0.06060606060606055,"last_synced_commit":"3de8eb1fa70fca113f6129f1f64db4c0372d61a6"},"previous_names":["venables/typed-route-handler"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/venables%2Ftyped-route-handler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/venables%2Ftyped-route-handler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/venables%2Ftyped-route-handler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/venables%2Ftyped-route-handler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/venables","download_url":"https://codeload.github.com/venables/typed-route-handler/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247284944,"owners_count":20913704,"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":[],"created_at":"2024-09-05T00:01:01.186Z","updated_at":"2025-04-05T04:08:45.085Z","avatar_url":"https://github.com/venables.png","language":"TypeScript","readme":"\u003ch1 align=\"center\"\u003etyped-route-handler\u003c/h1\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cstrong\u003eType-safe Route Handlers for Next.js\u003c/strong\u003e\n\u003c/div\u003e\n\n```ts\nimport type { Handler } from 'typed-route-handler'\n\ntype ResponseData = {\n  result: string\n  over: number\n}\n\nexport const GET: Handler\u003cResponseData\u003e = async (req) =\u003e {\n  return NextResponse.json({\n    result: \"this response is type-checked\",\n    over: 9000\n  })\n}\n```\n\n\u003e [!NOTE]\n\u003e This library is designed for **Next.js 15 and higher**. To use this library with Next.js 14 or earlier, use typed-route-handler version `0.3.0`.\n\n## Features\n\n- ✅ **Type-safe** route handler responses\n- ✅ **Type-safe** route handler parameters\n- ✅ Full **zod compatibility**\n- ✅ Production ready\n\n## Installation\n\n```sh\nnpm i -D typed-route-handler\n```\n\nThis library can be installed as a devDependency when only used for types. If you'd like to use the [wrapper](#wrapper-function) function, you can install it as a regular dependency.\n\n## Usage\n\nTyped handler is easy to use: In the simplest case, just add the type `Handler` to your route handler and you're good to go!\n\n```diff\n+ import type { Handler } from 'typed-route-handler'\n\n- export const GET = async (req: NextRequest) =\u003e {\n+ export const GET: Handler = async (req) =\u003e {\n    // ...\n  }\n```\n\n## Typed Responses\n\nThe real magic comes when you add typing to your responses.\n\n```ts\nimport { NextResponse } from \"next\"\nimport type { Handler } from 'typed-route-handler'\n\ntype ResponseData = {\n  name: string\n  age: number\n}\n\nexport const GET: Handler\u003cResponseData\u003e = (req) =\u003e {\n  return NextResponse.json({\n    name: \"Bluey\",\n    age: \"seven\", // \u003c-- this will cause a type error\n  })\n}\n```\n\n## Typed Parameters\n\nWe can also add type verification to our parameters. Each parameter `Context` extends from `NextRouteContext`.  \n\n```ts\n// app/api/[name]/route.ts\nimport { NextResponse } from \"next/server\"\nimport { type Handler, type NextRouteContext } from \"typed-route-handler\"\n\ntype ResponseData = {\n  name: string\n}\n\ntype Context = NextRouteContext\u003c{\n  name: string\n}\u003e\n\nexport const GET: Handler\u003cResponseData, Context\u003e = async (req, context) =\u003e {\n  const { name } = await context.params // \u003c-- this will be type-safe\n\n  return NextResponse.json({\n    name\n  })\n}\n```\n\nNote that this does not perform any runtime type-checking. To do that, you can use the zod types:\n\n```ts\nimport { NextResponse } from \"next/server\"\nimport { z } from \"zod\"\nimport { type Handler } from \"typed-route-handler\"\n\ntype ResponseData = {\n  name: string\n}\n\nconst contextSchema = z.object({\n  params: z.promise( // \u003c-- note the promise here, for next.js 15+\n    z.object({\n      name: z.string()\n    })\n  )\n})\n\nexport const GET: Handler\u003cResponseData, z.infer\u003ctypeof contextSchema\u003e\u003e = async (req, context) =\u003e {\n  const { name } = await context.params // \u003c-- this will still be type-safe\n\n  // or you can parse the schema:\n  const { params } = contextSchema.parse(context)\n  const { name } = await params\n\n\n  return NextResponse.json({\n    name\n  })\n}\n```\n\n## Wrapper function\n\nIn addition to providing these types, the library also provides a convenience wrapper function `handler` which simply applies the Handler type to the function. Since this is a no-op, it is recommended to use the `Handler` type directly.\n\nNOTE: If you use this method, you should install this package as a `dependency`\n\n```ts\nimport { handler } from \"typed-route-handler\"\nimport { NextResponse } from 'next/server'\n\ntype ResponseBody = {\n  balance: number\n}\n\nexport const GET = handler\u003cResponseBody\u003e(async (req) =\u003e {\n  return NextResponse.json({\n    balance: 9_000\n  })\n})\n```\n\n### Usage with modified `req`s (e.g. next-auth)\n\nWhen using this library with `next-auth` or other libraries which modify the `req` objects, you can pass a 3rd type to the `handler` call, representing modified Request object type. For example:\n\n```ts\nimport { auth } from '@/auth'\nimport { type NextAuthRequest } from 'next-auth'\nimport { handler, type type NextRouteContext } from 'typed-route-handler'\n\nexport const GET = auth(\n  handler\u003cResponseBody, NextRouteContext, NextAuthRequest\u003e((req, ctx) =\u003e {\n    if (!req.auth?.user) {\n      unauthorized()\n    }\n\n    // ...\n  })\n)\n```\n\n## 🏰 Production Ready\n\nAlready widely used in high-traffic production apps in [songbpm](https://songbpm.com), [jog.fm](https://jog.fm), [usdc.cool](https://usdc.cool), as well as all [StartKit](https://github.com/startkit-dev/next) projects.\n\n## ❤️ Open Source\n\nThis project is MIT-licensed and is free to use and modify for your own projects.\n\nIt was created by [Matt Venables](https://venabl.es).\n","funding_links":[],"categories":["TypeScript","**1. Libraries**"],"sub_categories":["Others"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvenables%2Ftyped-route-handler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvenables%2Ftyped-route-handler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvenables%2Ftyped-route-handler/lists"}