Typia

Summary

typia@next uses the ttsc toolchain.

This setup targets TypeScript-Go, the Go migration of the TypeScript compiler. ttsc provides the Go-based plugin toolchain, and typia@next uses the Go-rewritten typia transform.

ttsc: build, check, and watch TypeScript projects
ttsx: execute TypeScript directly with type checking
@ttsc/unplugin: run ttsc plugins from bundlers

Note

@typescript/native-preview is not a stable TypeScript release yet, and typia@next is also an experimental release of typia.

Also, you must use ttsc and ttsx. The stock tsc, ts-node, and tsx cannot apply the typia transform, so they will not work.

Setup

Install

npm

Terminal


npm i typia@next
npm i -D ttsc @typescript/native-preview

pnpm

Terminal


pnpm i typia@next
pnpm i -D ttsc @typescript/native-preview

yarn

Terminal


yarn add typia@next
yarn add -D ttsc @typescript/native-preview

bun

Terminal


bun add typia@next
bun add -d ttsc @typescript/native-preview

Keep your TypeScript project strict.

tsconfig.json


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

Compile

Use ttsc to build your TypeScript project. It compiles your sources and applies the typia transform in one step.

npm

Terminal


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

pnpm

Terminal


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

yarn

Terminal


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

bun

Terminal


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

Execute

Use ttsx to run a TypeScript file directly, without a build step.

npm

Terminal


npx ttsx src/index.ts

pnpm

Terminal


pnpm ttsx src/index.ts

yarn

Terminal


yarn ttsx src/index.ts

bun

Terminal


bun ttsx src/index.ts

Bundlers

Install

Use @ttsc/unplugin when your project is built by a bundler.

ttsc is enough for a normal TypeScript build, but bundlers run their own build pipeline. @ttsc/unplugin connects the ttsc transform to that pipeline.

npm

Terminal


npm i -D @ttsc/unplugin

pnpm

Terminal


pnpm i -D @ttsc/unplugin

yarn

Terminal


yarn add -D @ttsc/unplugin

bun

Terminal


bun add -d @ttsc/unplugin

Configuration

Currently, @ttsc/unplugin supports the following bundlers:

Vite
Next.js
Rollup
Rolldown
esbuild
Webpack
Rspack
Farm
Bun

Then add the matching plugin to your bundler config. Import path must match the bundler you are using.

Vite

vite.config.ts


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

Next.js

next.config.mjs


import withTtsc from "@ttsc/unplugin/next";
 
/** @type {import("next").NextConfig} */
const nextConfig = {
  reactStrictMode: true,
};
 
export default withTtsc(nextConfig);

Rollup

rollup.config.ts


import ttsc from "@ttsc/unplugin/rollup";
 
export default {
  input: "src/index.ts",
  output: {
    dir: "dist",
    format: "esm",
  },
  plugins: [ttsc()],
};

Rolldown

rolldown.config.ts


import ttsc from "@ttsc/unplugin/rolldown";
import { defineConfig } from "rolldown";
 
export default defineConfig({
  input: "src/index.ts",
  output: {
    dir: "dist",
    format: "esm",
  },
  plugins: [ttsc()],
});

esbuild

esbuild.config.ts


import ttsc from "@ttsc/unplugin/esbuild";
import { build } from "esbuild";
 
await build({
  entryPoints: ["src/index.ts"],
  outdir: "dist",
  bundle: true,
  plugins: [ttsc()],
});

Webpack

webpack.config.mjs


import ttsc from "@ttsc/unplugin/webpack";
 
export default {
  entry: "./src/index.ts",
  output: {
    path: new URL("./dist", import.meta.url).pathname,
  },
  plugins: [ttsc()],
};

Rspack

rspack.config.mjs


import ttsc from "@ttsc/unplugin/rspack";
 
export default {
  entry: "./src/index.ts",
  plugins: [ttsc()],
};

Farm

farm.config.ts


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

Bun

build.ts


import ttsc from "@ttsc/unplugin/bun";
 
await Bun.build({
  entrypoints: ["src/index.ts"],
  outdir: "dist",
  plugins: [ttsc()],
});

Put the plugin in the same config file that already builds your application. For example, a Vite app uses vite.config.ts, a Next.js app uses next.config.mjs, and a Webpack app uses webpack.config.mjs.

After that, run the normal build command of your framework or bundler.

Project

If your bundler should read another TypeScript config file, pass project.

Vite

vite.config.ts


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

Next.js

next.config.mjs


import withTtsc from "@ttsc/unplugin/next";
 
/** @type {import("next").NextConfig} */
const nextConfig = {
  reactStrictMode: true,
};
 
export default withTtsc(nextConfig, {
  project: "tsconfig.bundle.json",
});

Rollup

rollup.config.ts


import ttsc from "@ttsc/unplugin/rollup";
 
export default {
  input: "src/index.ts",
  output: {
    dir: "dist",
    format: "esm",
  },
  plugins: [
    ttsc({
      project: "tsconfig.bundle.json",
    }),
  ],
};

Rolldown

rolldown.config.ts


import ttsc from "@ttsc/unplugin/rolldown";
import { defineConfig } from "rolldown";
 
export default defineConfig({
  input: "src/index.ts",
  output: {
    dir: "dist",
    format: "esm",
  },
  plugins: [
    ttsc({
      project: "tsconfig.bundle.json",
    }),
  ],
});

esbuild

esbuild.config.ts


import ttsc from "@ttsc/unplugin/esbuild";
import { build } from "esbuild";
 
await build({
  entryPoints: ["src/index.ts"],
  outdir: "dist",
  bundle: true,
  plugins: [
    ttsc({
      project: "tsconfig.bundle.json",
    }),
  ],
});

Webpack

webpack.config.mjs


import ttsc from "@ttsc/unplugin/webpack";
 
export default {
  entry: "./src/index.ts",
  output: {
    path: new URL("./dist", import.meta.url).pathname,
  },
  plugins: [
    ttsc({
      project: "tsconfig.bundle.json",
    }),
  ],
};

Rspack

rspack.config.mjs


import ttsc from "@ttsc/unplugin/rspack";
 
export default {
  entry: "./src/index.ts",
  plugins: [
    ttsc({
      project: "tsconfig.bundle.json",
    }),
  ],
};

Farm

farm.config.ts


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

Bun

build.ts


import ttsc from "@ttsc/unplugin/bun";
 
await Bun.build({
  entrypoints: ["src/index.ts"],
  outdir: "dist",
  plugins: [
    ttsc({
      project: "tsconfig.bundle.json",
    }),
  ],
});

The project path is resolved from the current working directory.

Transform Options

Add compilerOptions.plugins only when you want to change transform options.

tsconfig.json


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

functional: validate function types
numeric: reject NaN from number
finite: reject both NaN and Infinity from number
undefined: set false to skip explicit undefined checks

Note

If you use the default transform options, do not add compilerOptions.plugins to tsconfig.json.

ttsc automatically applies the typia transform. This is the difference from the legacy setup.