Setup

typia is a compile-time transformer, so your build has to run through the TypeScript 7 transformer path. Install typia, typescript, and ttsc; then build with ttsc or execute TypeScript directly with ttsx.

Install

npm i typia
npm i -D ttsc typescript

pnpm i typia
pnpm i -D ttsc typescript

yarn add typia
yarn add -D ttsc typescript

bun add typia
bun add -d ttsc typescript

Keep the TypeScript project strict:

{
  "compilerOptions": {
    "strict": true
  }
}

Build

Use ttsc where you would normally run a TypeScript compiler:

npx ttsc
npx ttsc --noEmit
npx ttsc --watch

pnpm ttsc
pnpm ttsc --noEmit
pnpm ttsc --watch

yarn ttsc
yarn ttsc --noEmit
yarn ttsc --watch

bun ttsc
bun ttsc --noEmit
bun ttsc --watch

Content Mappers

With TypeScript 7.1, typia can inspect types supplied by the content mappers in your tsconfig.json. Build with explicit permission to run those mapper programs:

npx ttsc --runExternalCode -p tsconfig.json

The flag executes your project’s mapper programs. Without it, the compiler rejects mapper execution. Typia uses the mapped declarations for validators and schemas, including types imported from files such as .sql. TypeScript 7.0 has no content mappers.

Execute Without Building

Use ttsx instead of runners that strip TypeScript before typia can transform it:

npx ttsx src/index.ts

pnpm ttsx src/index.ts

yarn ttsx src/index.ts

bun ttsx src/index.ts

Bundlers

Bundlers such as Vite, Next.js, Rollup, esbuild, Webpack, Rspack, Farm, and Bun run their own TypeScript pipeline. Install @ttsc/unplugin and add the matching plugin to the bundler config.

npm i -D @ttsc/unplugin

import ttsc from "@ttsc/unplugin/vite";
import { defineConfig } from "vite";
 
export default defineConfig({
  plugins: [ttsc()],
});

If the bundler should use a config other than tsconfig.json, pass project:

import ttsc from "@ttsc/unplugin/vite";
import { defineConfig } from "vite";
 
export default defineConfig({
  plugins: [
    ttsc({
      project: "tsconfig.bundle.json",
    }),
  ],
});

Transform Options

Most projects do not need this section. Add compilerOptions.plugins only when you want to change an optional typia transform flag:

{
  "compilerOptions": {
    "strict": true,
    "strictNullChecks": true,
    "plugins": [
      {
        "transform": "typia/lib/transform",
        "functional": true,
        "numeric": true,
        "finite": true
      }
    ]
  }
}

Verify

Drop this into your project and run it through the same command you use for the application:

import typia from "typia";
 
console.log(typia.is<{ id: string }>({ id: "ok" }));
// true

If it prints true, the transform ran. If it throws Error on typia.<method>(): no transform has been configured., the command bypassed ttsc, ttsx, or @ttsc/unplugin. Configure one of those transform paths, then run npx ttsc --noEmit; that compiler pass exposes the underlying TypeScript or TS(typia.<method>) transform diagnostic instead of reaching the runtime fallback.

typia attributes a call by the file its declaration comes from, so a project-local declare module "typia" takes the call out of typia’s own declarations and the transform no longer recognizes it. That case is reported at build time as error TS(typia.<method>): this call resolved to a declaration in <file> instead of typia's own, so no transform was applied. Delete the redeclaration, or give it another module name.

Where to go next

• First validator after setup: is, assert, validate
• Why typia needs a transform: Pure TypeScript
• Bundled framework recipes: Utilization Cases