Skip to Content
📖 Guide Documents📦 SetupCurrent (TypeScript 7)

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.

Note

Projects pinned to typia 12 and TypeScript below 7 use the legacy TypeScript setup. The rest of this page covers the current typia release and TypeScript 7.

Important

typia’s native transform requires ttsc 0.37.0 or newer. It supports both TypeScript 7.0 and 7.1; ttsc selects the compiler target from your installed TypeScript version. Version 0.37.0 keys typia’s cached outputs by the environment variables the transform actually reads, so a warm ttsx run keeps reusing them across unrelated environment changes.

Install

Terminal
npm i typia npm i -D ttsc typescript

Native build cache

ttsc builds typia’s native plugin from Go source on first use, using its bundled Go toolchain; you do not need a separate Go installation. A company policy that prohibits executing Go still applies to that cold build. The compiled plugin is specific to the installed compiler, ttsc and plugin source, so its cached executable is reused only when those build inputs match.

Persist node_modules/.cache/ttsc/plugins across CI jobs to avoid repeating the native build. Persist node_modules/.cache/ttsc/go-build as an optional accelerator for builds whose plugin identity changes. Restore these directories after dependency installation, use a cache key containing the runner OS, architecture and lockfile hash, and do not persist temporary ttsx run directories. A monorepo shares the cache under its workspace root. The ttsc build cache guide  contains GitHub Actions and Docker examples, cache-root overrides and verification commands.

The native plugin cache and checked application results are separate. Typia supplies ttsc with the actual compiler/configuration/resolution observations, linked-hook input reports and compiler-owned output provenance needed to decide whether an unchanged ttsx result can be reused. Missing or incomplete proof retains a fresh build. Other selected plugins must also support their negotiated observation protocols; typia’s support does not grant completeness to a separate aggregate host such as nestia. See ttsx checked-result reuse .

Keep the TypeScript project strict:

tsconfig.json
{ "compilerOptions": { "strict": true } }

Build

Use ttsc where you would normally run a TypeScript compiler:

Terminal
npx ttsc npx ttsc --noEmit npx 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:

Terminal
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:

Terminal
npx ttsx src/index.ts
Important

The stock tsc, ts-node, and tsx commands do not load typia’s transform. Use ttsc, ttsx, or @ttsc/unplugin.

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.

Terminal
npm i -D @ttsc/unplugin
vite.config.ts
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:

vite.config.ts
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:

tsconfig.json
{ "compilerOptions": { "strict": true, "strictNullChecks": true, "plugins": [ { "transform": "typia/lib/transform", "functional": true, "numeric": true, "finite": true } ] } }
FlagDefaultWhat it does
functionalfalseValidate function-typed properties as well as data properties
numericfalseReject NaN when a property is typed as number
finitefalseReject NaN and Infinity when a property is typed as number

Verify

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

src/check-setup.ts
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

Last updated on