Typia

Legacy (TypeScript v6)

This is the production-stable path. It uses ts-patch on top of the JavaScript TypeScript compiler and is what current published typia releases (v6 line) plug into.

The fastest way to install: run the wizard.

npm

Terminal


npm install typia
npx typia setup

pnpm

Terminal


pnpm install typia
pnpm typia setup --manager pnpm

yarn

Terminal


# Yarn Berry is NOT supported
yarn add typia
yarn typia setup --manager yarn

bun

Terminal


bun add typia
bun typia setup --manager bun

npx typia setup installs typescript and ts-patch, adds the typia/lib/transform plugin entry to your tsconfig.json, and wires up a prepare script so ts-patch install runs after every npm install. After it finishes, plain tsc builds your project with the typia transform applied.

Warning

CI tip. The prepare script runs ts-patch install after every install — but npm ci --ignore-scripts (which most production / Docker multi-stage installs use) silently skips it. Your production build then compiles without the typia transform, and validators that worked locally throw "no transform has been configured" at runtime. Run npx ts-patch install explicitly right after the npm ci --ignore-scripts step in your pipeline.

If your build pipeline uses a bundler (Vite, Next.js, Webpack, esbuild, …), you’ll also want @typia/unplugin.

If your build pipeline uses Babel, SWC, or another tool that doesn’t run TypeScript-compatible transformers, you have to fall back to the generation mode — typia writes the transformed *.ts files for you ahead of time.

How the transformer works

This is Ahead-of-Time (AOT) compilation.

When you write typia.createIs<IMember>() and compile with tsc, the ts-patch-patched compiler replaces that call site with a hand-written checker specialized to IMember. There is no runtime schema — only the JavaScript that does exactly the comparisons your IMember type implies.

TypeScript Source

examples/src/validators/is.ts


import typia, { tags } from "typia";
import { v4 } from "uuid";
 
const matched: boolean = typia.is<IMember>({
  id: v4(),
  email: "samchon.github@gmai19l.com",
  age: 30,
});
console.log(matched); // true
 
interface IMember {
  id: string & tags.Format<"uuid">;
  email: string & tags.Format<"email">;
  age: number &
    tags.Type<"uint32"> &
    tags.ExclusiveMinimum<19> &
    tags.Maximum<100>;
}

Two requirements follow from this:

The build has to run TypeScript-with-transformers. That means stock tsc patched by ts-patch, or a bundler plugin that wraps the same machinery. Babel and SWC strip types before any transformer can see them, so they’re not supported in this mode — use generation mode instead.
strict (or at least strictNullChecks) has to be on. Without strict null checking, your types lie about which fields can be null/undefined, and the emitted validator will lie with them.

Wizard setup

The recommended way.

npm

Terminal


npm install typia
npx typia setup

pnpm

Terminal


pnpm install typia
pnpm typia setup --manager pnpm

yarn

Terminal


# Yarn Berry is NOT supported
yarn add typia
yarn typia setup --manager yarn

bun

Terminal


bun add typia
bun typia setup --manager bun

The wizard does three things:

Installs typescript and ts-patch if they aren’t already devDependencies.
Adds { "transform": "typia/lib/transform" } to compilerOptions.plugins in tsconfig.json.
Adds "prepare": "ts-patch install" to package.json’s scripts.

That’s everything. Run npm run prepare once (or let it run automatically on the next npm install) and tsc will apply the typia transform from then on.

Manual setup

If you’d rather configure it by hand, here’s what the wizard does:

npm

Terminal


npm install typia
npm install -D typescript ts-patch

pnpm

Terminal


pnpm install typia
pnpm install -D typescript ts-patch

yarn

Terminal


yarn add typia
yarn add -D typescript ts-patch

bun

Terminal


bun add typia
bun add -d typescript ts-patch

Add the transform plugin to tsconfig.json:

tsconfig.json


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

Add the prepare script to package.json:

package.json


{
  "scripts": {
    "prepare": "ts-patch install"
  },
  "dependencies": {
    "typia": "^6.0.6"
  },
  "devDependencies": {
    "ts-patch": "^3.2.0",
    "typescript": "^5.4.5"
  }
}

Run prepare once so ts-patch patches your local typescript:

npm

Terminal


npm run prepare

pnpm

Terminal


pnpm prepare

yarn

Terminal


yarn prepare

bun

Terminal


bun prepare

After that, plain tsc applies the transform.

Bundlers

`@typia/unplugin`

@typia/unplugin integrates the typia transform into bundlers. It supports:

Install it alongside typia:

npm

Terminal


npm install typia
npx typia setup
 
npm install -D @typia/unplugin

pnpm

Terminal


pnpm install typia
pnpm typia setup --manager pnpm
 
pnpm install -D @typia/unplugin

yarn

Terminal


# Yarn Berry is NOT supported
yarn add typia
yarn typia setup --manager yarn
 
yarn add -D @typia/unplugin

bun

Terminal


bun add typia
bun typia setup
 
bun add -D @typia/unplugin

Then add the matching plugin import to your bundler config:

Vite

You can run any other plugin alongside @typia/unplugin in Vite — including @vitejs/plugin-react-swc. @typia/unplugin rewrites the TypeScript source before the next plugin sees it, so they don’t conflict.

vite.config.ts


import UnpluginTypia from '@typia/unplugin/vite'
 
export default defineConfig({
  plugins: [
    UnpluginTypia({ /* options */ })
  ],
})

Next.js

next.config.mjs


import unTypiaNext from "@typia/unplugin/next";
 
/** @type {import('next').NextConfig} */
const config = {
  // your existing Next.js config
};
export default unTypiaNext(
  config,
  {} // options of @typia/unplugin
);

esbuild

esbuild.config.js


import { build } from 'esbuild'
import UnpluginTypia from '@typia/unplugin/esbuild';
 
build({
  plugins: [
    UnpluginTypia({ /* options */ }),
  ],
});

Bun.runtime

Make a preload.ts:

preload.ts


import { plugin } from 'bun';
import UnpluginTypia from '@typia/unplugin/bun'
 
plugin(UnpluginTypia({ /* options */ }))

Then point bunfig.toml at it:

bunfig.toml


preload = ["./preload.ts"]
 
[test]
preload = ["./preload.ts"]

Now bun run and bun test both apply the transform:

Terminal


bun run index.ts

Bun.build

Build.ts


import UnpluginTypia from '@typia/unplugin/bun'
 
await Bun.build({
  entrypoints: ["./index.ts"],
  outdir: "./out",
  plugins: [UnpluginTypia(/* options */)]
});

Full options reference lives in the @typia/unplugin README.

Webpack

@typia/unplugin supports Webpack out of the box. The instructions below are the manual ts-loader route for projects that prefer to wire it themselves.

npm

Terminal


# typia
npm install typia
npx typia setup
 
# webpack + ts-loader
npm install -D ts-loader webpack webpack-cli

pnpm

Terminal


# typia
pnpm install typia
pnpm typia setup --manager pnpm
 
# webpack + ts-loader
pnpm install -D ts-loader webpack webpack-cli

yarn

Terminal


# Yarn Berry is NOT supported
# typia
yarn add typia
yarn typia setup --manager yarn
 
# webpack + ts-loader
yarn add -D ts-loader webpack webpack-cli

bun

Terminal


# typia
bun add typia
bun typia setup
 
# webpack + ts-loader
bun add -d ts-loader webpack webpack-cli

ts-loader runs the patched tsc, so the typia transform applies automatically. Configure as usual:

webpack.config.js


const path = require("path");
 
module.exports = {
  entry: ["./src/index.tsx"],
  output: {
    path: path.join(__dirname, "dist"),
    filename: "index.js",
  },
  optimization: { minimize: false },
  mode: "development",
  target: "node",
  module: {
    rules: [
      {
        test: /\.ts$/,
        exclude: /node_modules/,
        loader: "ts-loader",
      },
    ],
  },
  resolve: {
    extensions: [".tsx", ".ts", ".js"],
  },
};

Build with npx webpack. When you strip dev dependencies for production, also pass --ignore-scripts to skip ts-patch install (which would fail because typescript is no longer present):

npm

Terminal


npx webpack
npm ci --omit=dev --ignore-scripts

pnpm

Terminal


pnpm webpack
pnpm install --production --ignore-scripts

yarn

Terminal


yarn webpack
rm -rf node_modules
yarn install --production --ignore-scripts --immutable

bun

Terminal


bun webpack
bun install --production --ignore-scripts

For Node.js backend bundling — including the popular “single bundled JS file with no node_modules” pattern — see the Nestia setup guide .

NX

npm

Terminal


npm install typia
npx typia setup

pnpm

Terminal


pnpm install typia
pnpm typia setup --manager pnpm

yarn

Terminal


# Yarn Berry is NOT supported
yarn add typia
yarn typia setup --manager yarn

bun

Terminal


bun add typia
bun typia setup --manager bun

After installation, make sure the prepare script runs ts-patch install, then add the typia plugin to each @nx/js package’s tsconfig.lib.json:

tsconfig.lib.json


{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "../../dist/out-tsc",
    "declaration": true,
    "types": [],
    "plugins": [{ "transform": "typia/lib/transform" }]
  },
  "include": ["**/*.ts"],
  "exclude": ["jest.config.ts", "**/*.spec.ts", "**/*.test.ts"]
}

Warning

Nx swallows transformer errors. If typia detects an unsupported type (or anything else), nx <package>:build will succeed but emit JavaScript without the typia transform applied. At runtime you’ll see:


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

To get the actual error, run tsc directly:

project.json


"targets": {
  "build:validate:typia": {
    "executor": "nx:run-commands",
    "options": {
      "commands": [
        "tsc --project packages/<package-name>/tsconfig.lib.json --outDir dist/packages/typiaTest"
      ]
    }
  }
}

Nx’s own transformers option on @nx/js does not work with typia — it expects a before hook that typia doesn’t expose, because typia operates through ts-patch instead.

Generation

npx typia generate is the fallback for build pipelines where a TypeScript transformer can’t run — Babel in Create-React-App, raw SWC, and so on. typia reads the input directory or the positional TypeScript source files you pass, expands every typia.*<T>() call site, and writes the transformed source files to the output directory. Your bundler then compiles those transformed files normally.

npm

Terminal


npm install typia
npm install -D typescript ttsc @typescript/native-preview
 
npx typia generate \
  --input src/templates \
  --output src/generated \
  --project tsconfig.json

pnpm

Terminal


pnpm install typia
pnpm install -D typescript ttsc @typescript/native-preview
 
pnpm typia generate \
  --input src/templates \
  --output src/generated \
  --project tsconfig.json

yarn

Terminal


yarn add typia
yarn add -D typescript ttsc @typescript/native-preview
 
yarn typia generate \
  --input src/templates \
  --output src/generated \
  --project tsconfig.json

bun

Terminal


bun add typia
bun add -d typescript ttsc @typescript/native-preview
 
bun typia generate \
  --input src/templates \
  --output src/generated \
  --project tsconfig.json

When to use it:

Build tool	Use this instead
Create-React-App / Babel	`typia generate`
Vite / esbuild	`@typia/unplugin`
SWC alone	`typia generate`
Bundlers with SWC inside (Next.js, Vite, …)	`@typia/unplugin`

Use --input when all templates live under one directory. When templates live beside feature modules, pass file paths or globs instead:

Terminal


npx typia generate \
  --output src/generated \
  --project tsconfig.json \
  "src/**/*.typia.ts"

File/glob mode writes each selected file as --output/<basename>. Duplicate basenames are rejected instead of overwritten.

--project accepts a tsconfig.json or jsconfig.json file, or a directory containing either file. When you omit --project, typia searches from the current working directory upward for the nearest tsconfig.json or jsconfig.json.

The input directory or file list contains TypeScript source files that import typia and re-export validators. typia reads each file, applies the transform, and writes the result to --output:

TypeScript Input

examples/src/templates/check.ts


import typia from "typia";
 
import { IMember } from "../structures/IMember";
 
export const check = typia.createIs<IMember>();

Caution

Why non-standard compilers aren’t supported directly.

Babel and SWC strip type annotations before any transformer runs. typia needs the type information, so it can’t operate inside those toolchains. Generation mode works around the limitation by running typia ahead of time, producing plain .ts files that any tool can then compile.

Where to go next

Modern TypeScript-Go alternative → TypeScript-Go setup
First validator after setup → is · assert · validate
Why typia needs a transform at all → Pure TypeScript

Legacy (TypeScript v6)

npm

pnpm

yarn

bun

How the transformer works

TypeScript Source

Compiled JavaScript

Wizard setup

npm

pnpm

yarn

bun

Manual setup

npm

pnpm

yarn

bun

npm

pnpm

yarn

bun

Bundlers

@typia/unplugin

npm

pnpm

yarn

bun

Vite

Next.js

esbuild

Bun.runtime

Bun.build

Webpack

npm

pnpm

yarn

bun

npm

pnpm

yarn

bun

NX

npm

pnpm

yarn

bun

Generation

npm

pnpm

yarn

bun

TypeScript Input

Generated TypeScript

Where to go next

`@typia/unplugin`