Step 1 — Install

We’ll set up a fresh project that compiles with ttsc (the Go-rewritten TypeScript compiler that knows how to run the typia transform). If you already have a TypeScript project, you can install into that — just make sure your build command runs ttsc instead of tsc.

The legacy ts-patch setup also works (setup/legacy). The tutorial uses the modern ttsc path because it’s the simpler experience.

Create the project

mkdir typia-tutorial && cd typia-tutorial
npm init -y
 
npm i typia@next
npm i -D ttsc @typescript/native-preview @types/node

mkdir typia-tutorial && cd typia-tutorial
pnpm init
 
pnpm i typia@next
pnpm i -D ttsc @typescript/native-preview @types/node

mkdir typia-tutorial && cd typia-tutorial
yarn init -y
 
yarn add typia@next
yarn add -D ttsc @typescript/native-preview @types/node

mkdir typia-tutorial && cd typia-tutorial
bun init -y
 
bun add typia@next
bun add -d ttsc @typescript/native-preview @types/node

Configure TypeScript

Drop this into tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Preserve",
    "moduleResolution": "Bundler",
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

target: ES2022 is needed by the later tutorial steps (top-level await in step 5). module: Preserve + moduleResolution: Bundler lets ttsx handle module loading for you — you can write import { Bookmark } from "./bookmark" without the .js extension that raw Node ESM would otherwise require.

That’s it — ttsc discovers the typia transform from typia/package.json automatically. You do not add compilerOptions.plugins here. (That step is only for the legacy ts-patch path.)

"strict": true matters: without strict null checks your interfaces lie about which fields can be null or undefined, and the emitted validator will lie with them.

Verify your setup

Create the src directory and write a one-line smoke test:

mkdir -p src

import typia from "typia";
 
console.log(typia.is<{ id: string }>({ id: "ok" }));
//                                  ^---- transform turns this into an inline checker

Then run it without building first — ttsx is the typia-aware counterpart of ts-node / tsx:

npx ttsx src/check-setup.ts

pnpm ttsx src/check-setup.ts

yarn ttsx src/check-setup.ts

bun ttsx src/check-setup.ts

You should see:

true

If you see this instead:

Error on typia.is(): no transform has been configured

…you’re running stock tsc / tsx / ts-node somewhere — those compilers don’t know about typia’s transform. The fix is always to use ttsc for building and ttsx for running. Double-check the command you ran and the scripts in package.json.

Build script (for later)

You’ll want a quick build script for later steps. Add this to package.json:

{
  "scripts": {
    "build": "ttsc",
    "check": "ttsc --noEmit"
  }
}

Now npm run build compiles and npm run check type-checks without emitting. The rest of the tutorial uses npx ttsx <file> (or pnpm ttsx <file>, etc.) directly for ad-hoc runs.

→ Step 2: First validator