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.
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.
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
npm
npm i typia
npm i -D ttsc typescriptNative 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:
{
"compilerOptions": {
"strict": true
}
}Build
Use ttsc where you would normally run a TypeScript compiler:
npm
npx ttsc
npx ttsc --noEmit
npx ttsc --watchContent 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.jsonThe 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:
npm
npx ttsx src/index.tsThe 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.
npm i -D @ttsc/unpluginimport 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
}
]
}
}| Flag | Default | What it does |
|---|---|---|
functional | false | Validate function-typed properties as well as data properties |
numeric | false | Reject NaN when a property is typed as number |
finite | false | Reject 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:
import typia from "typia";
console.log(typia.is<{ id: string }>({ id: "ok" }));
// trueIf 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