tag-rpc

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


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

// 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

;

}
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