End-to-end type safety for Next.js Route Handlers
npm install tag-rpcTagRPC
Note: Stable versions start from 1.1.5
End-to-end type safety for Next.js Route Handlers. TagRPC bridges the gap between your Next.js API routes and your frontend with zero boilerplate and 100% type safety using simple XML-like tags.
Features
Zero Schemas: No Zod or Valibot required. Define your types directly in your route.ts file using standard TypeScript syntax.
Auto-Generation: A watcher process tracks your app/api folder and updates types instantly as you save files.
Named Routes: Access your APIs by function name (e.g., api.getUser()) instead of manually managing URL strings like /api/users/[id].
Ultra-Lightweight: There are zero runtime dependencies in your production bundle.
Installation
Bash
npm install tag-rpc
Setup
1. Tag Your Routes
Inside any app/api/\\/route.ts file, add tags inside a backtick string to define your route's metadata. The scanner will parse these tags to build your registry.
TypeScript Example
// app/api/users/[id]/route.ts
getUser
id: string;
name: string;
email?: string;
id: string;
name: string;
includeemail: string;
export async function GET(req: Request, { params }: { params: { id: string } }) {
// Your implementation logic
} 2. Run the Scanner
Add the scanner to your package.json scripts to keep your types in sync during development.
JSON Example
"scripts": {
"rpc": "tag-rpc",
"rpc:watch": "tag-rpc --watch",
"build": "tag-rpc && next build"
} 3. Initialize the Client and Helper Types
Create an initialization file (e.g., lib/api.ts). This setup generates the client and exports helper types for use throughout your application.
TypeScript Example
import { createTagRPC, TypeOf } from 'tag-rpc';
import { ApiRoutes, namedRoutes } from '@/rpc/api-registry'; // Paths from generated file
// Initialize the RPC client
export const api = createTagRPC
// Export helper types for Responses, Queries, and Requests
export type RouteResponse
TypeOf
export type RouteQuery
TypeOf
export type RouteRequest
TypeOf
Usage
You can now utilize full autocomplete and type safety in your React components. The client automatically knows the path parameters, query parameters, and response shapes.
TypeScript Example
// components/UserCard.tsx
import { api } from '@/lib/api';
const UserCard = async ({ id }: { id: string }) => {
// Fully typed: provides IDE completion for pathParams and the response object
const user = await api.getUser({
pathParams: { id }
});
return {user.name};
}
Configuration (Optional)
Create a tagrpc.config.ts (or .mjs) in your root directory to customize the scanning behavior.
Run: npx tagrpc-generate-config
TypeScript Example
export default {
appDir: 'app',
apiRoutesDir:"app/api",// Location of your Next.js route handlers folder
outputFile: 'app/api-registry.ts'// Destination for generated types
};
License
MIT © Kelvin Mitau