Claude Code for Typia Validator — Workflow Guide

Written by Michael Lip · Solo founder of Zovo · $400K+ on Upwork · 100% JSS Join 50+ builders · More at zovo.one

The Setup

You are using Typia to generate runtime validators directly from TypeScript types — no schema duplication needed. Define your types once with standard TypeScript syntax, and Typia generates optimized validation, assertion, and serialization code at compile time. Claude Code can use Typia, but it writes Zod schemas alongside TypeScript types, duplicating definitions.

What Claude Code Gets Wrong By Default

  1. Creates Zod schemas that mirror TypeScript types. Claude defines interface User { name: string } and then const UserSchema = z.object({ name: z.string() }). Typia uses the TypeScript type directly: typia.createValidate<User>() — no schema duplication.

  2. Uses runtime reflection for validation. Claude writes custom validation with typeof checks. Typia generates AOT (ahead-of-time) optimized validation code from the TypeScript compiler, running 1000x faster than runtime schema validation.

  3. Misses the TypeScript compiler plugin requirement. Claude imports Typia and calls functions directly without configuring the transform. Typia requires ts-patch or @typia/transform in tsconfig.json — without the compiler plugin, Typia functions return empty validators.

  4. Skips JSDoc tag validation. Claude adds Zod refinements like .email() or .min(1). Typia uses JSDoc tags on TypeScript types: /** @format email */ email: string generates email validation without any schema library.

The CLAUDE.md Configuration

# Typia Runtime Validation Project

## Validation
- Library: Typia (AOT compile-time validator generation)
- Types: Standard TypeScript interfaces/types
- Compiler: ts-patch + typia/lib/transform in tsconfig.json
- JSDoc: @format, @minimum, @maximum for constraints

## Typia Rules
- Define types with standard TypeScript (interface, type)
- Validate: typia.validate<MyType>(input) returns IValidation
- Assert: typia.assert<MyType>(input) throws on failure
- Check: typia.is<MyType>(input) returns boolean
- Constraints via JSDoc: @format email, @minimum 0, @pattern regex
- TypeScript compiler plugin MUST be configured
- No schema duplication — types are the single source of truth
- Use typia.json.stringify<T>() for optimized JSON serialization

## Conventions
- Types in src/types/ directory (standard .ts interfaces)
- Validators generated from types — never write manual validators
- JSDoc tags for format constraints on type properties
- tsconfig.json must include typia transform plugin
- API route handlers use typia.assert<RequestBody>(req.body)
- Never install Zod — Typia replaces it entirely

Workflow Example

You want to validate API request bodies using existing TypeScript types. Prompt Claude Code:

“Create a User type with name (min 1 char), email (email format), and age (between 0 and 150). Use Typia to validate incoming API request bodies against this type without writing a separate schema.”

Claude Code should define a TypeScript interface with JSDoc constraints: /** @minLength 1 */ name: string, /** @format email */ email: string, /** @minimum 0 @maximum 150 */ age: number, then use typia.assert<User>(req.body) in the API handler to validate with zero schema duplication.

Common Pitfalls

  1. Missing ts-patch setup. Claude installs Typia but does not configure ts-patch or the compiler transform. Typia functions compile to no-ops without the transform — validation silently passes everything. Run ts-patch install and add the plugin to tsconfig.json.

  2. JSDoc tags on wrong scope. Claude puts JSDoc tags on the type alias instead of individual properties. Tags like @format email must be on the specific property, not on the interface declaration — property-level documentation is where Typia reads constraints.

  3. Build pipeline incompatibility. Claude uses Typia with a Vite/SWC/esbuild build that strips TypeScript without running the compiler. Typia needs the TypeScript compiler (tsc) to run its transform. Use tsc for the build step or configure the Typia bundler plugin for your build tool.