TagRPC 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

<GetRouteName> getUser </GetRouteName> <GetResponseType> id: string; name: string; email?: string; </GetResponseType> <GetRequestType> id: string; name: string; </GetRequestType> <GetQueryType> includeemail: string; </GetQueryType>

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<ApiRoutes, typeof namedRoutes>({ namedRoutes });

// Export helper types for Responses, Queries, and Requests export type RouteResponse = TypeOf<ApiRoutes, typeof namedRoutes, K, "Response">;

export type RouteQuery = TypeOf<ApiRoutes, typeof namedRoutes, K, "Query">;

export type RouteRequest = TypeOf<ApiRoutes, typeof namedRoutes, K, "Request">; 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 <div>{user.name}</div>;

} 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