trpc-scaffolder

# tRPC Scaffolder

Automate creation of type-safe tRPC endpoints with Zod validation.

**TL;DR**: Run scripts to create routers/schemas, register in `_app.ts`, validate with scripts.

---

## Auto-Triggers

Auto-triggered by keywords:
- "new endpoint", "create endpoint", "tRPC procedure"
- "new router", "API", "Zod schema"

---

## Quick Standards

### File Locations
```
lib/trpc/routers/
  _app.ts          # Register all routers here ⚠️
  {name}.ts        # Router files

lib/trpc/schemas/
  {entity}.schema.ts  # Zod schemas
```

### Router Pattern
```typescript
export const nameRouter = router({
  doThing: publicProcedure
    .input(inputSchema)
    .output(outputSchema)
    .mutation(async ({ input }) => { /* logic */ }),
});
```

### Schema Pattern
```typescript
export const inputSchema = z.object({
  field: z.string().min(1),
});

export type Input = z.infer<typeof inputSchema>;  // ⚠️ Required!
```

### Registration (Required!)
```typescript
// In _app.ts
export const appRouter = router({
  ai: aiRouter,
  name: nameRouter,  // ⬅️ Add new routers here
});
```

---

## Run Scripts

### Create Router
```bash
./.claude/skills/trpc-scaffolder/scripts/create-router.sh user
# Creates: lib/trpc/routers/user.ts
# ⚠️ Remember to register in _app.ts!
```

### Add Procedure
```bash
./.claude/skills/trpc-scaffolder/scripts/add-procedure.sh ai getHints query
# Outputs code snippet to add to router
```

### Create Schema
```bash
./.claude/skills/trpc-scaffolder/scripts/create-schema.sh hint
# Creates: lib/trpc/schemas/hint.schema.ts
```

### Validate Setup
```bash
./.claude/skills/trpc-scaffolder/scripts/validate-trpc.sh
# Checks: router registration, type exports
```

---

## Quick Reference

### Query vs Mutation
| Type | Use For | Method |
|------|---------|--------|
| Query | Fetch data (GET) | `.query(async ({ input }) => ...)` |
| Mutation | Modify data (POST/PUT/DELETE) | `.mutation(async ({ input }) => ...)` |

### Common Zod Patterns
| Type | Pattern | Example |
|------|---------|---------|
| String | `z.string().min(1).max(100)` | Name validation |
| Number | `z.number().int().min(0).max(10)` | Difficulty 0-10 |
| Email | `z.string().email()` | Email validation |
| Optional | `z.string().optional()` | Optional field |
| Array | `z.array(z.string()).min(1)` | At least 1 item |
| Enum | `z.enum(["a", "b", "c"])` | Fixed choices |
| Object | `z.object({ field: z.string() })` | Nested object |

### Naming Conventions
- **Routers**: `{domain}Router` (e.g., `aiRouter`, `userRouter`)
- **Procedures**: `camelCase` (e.g., `generateQuestions`, `getHints`)
- **Schemas**: `{action}{Entity}{Input\|Output}Schema`
- **Files**: `{entity}.schema.ts`, `{domain}.ts`

### Error Codes
| Code | When | Example |
|------|------|---------|
| `NOT_FOUND` | Resource doesn't exist | User not found |
| `BAD_REQUEST` | Invalid input | Validation failed |
| `UNAUTHORIZED` | Not authenticated | Login required |
| `FORBIDDEN` | Not authorized | Access denied |
| `INTERNAL_SERVER_ERROR` | Server error | API failure |

---

## Common Fixes

### Router Not Registered
```typescript
// ❌ Forgot this step
// ✅ Add to _app.ts:
import { userRouter } from "./user";
export const appRouter = router({ ai: aiRouter, user: userRouter });
```

### Missing Type Exports
```typescript
// ❌ Schema without types
export const userSchema = z.object({ name: z.string() });

// ✅ Always export inferred types
export type User = z.infer<typeof userSchema>;
```

### Wrong Procedure Type
```typescript
// ❌ Using mutation for fetching data
getData: publicProcedure.mutation(...)

// ✅ Use query for GET operations
getData: publicProcedure.query(...)
```

### Schema Validation Error
```typescript
// ❌ No validation
field: z.string()

// ✅ Add constraints
field: z.string().min(1, "Field is required")
```

---

## When to Load Additional Docs

**SKILL.md is self-sufficient for:**
- Creating routers and schemas
- Running scripts
- Fixing common errors

**Load additional docs when needed:**

| Need | Load |
|------|------|
| Step-by-step tutorial | `docs/quick-start-guide.md` |
| Advanced Zod patterns | `docs/trpc-patterns.md` (lines 1-80) |
| Error handling strategies | `docs/trpc-patterns.md` (lines 150-220) |
| Testing procedures | `docs/trpc-patterns.md` (lines 220-270) |
| Context & middleware | `docs/trpc-patterns.md` (lines 80-150) |

**Code examples:**
- ✅ Perfect: `examples/good-router.ts`, `examples/good-schema.ts`

**Full project docs:** `Docs/api-design.md`, `Docs/api-transition/trpc-migration.md`

---

**Version:** 1.0.0 | **Updated:** October 2025
**Pattern**: Follows quality-reviewer structure (optimized)