Typia Guide Documents

Summary

Terminal

npm install typia
npx typia setup

Terminal

pnpm install typia
pnpm typia setup --manager pnpm

Terminal

# YARN BERRY IS NOT SUPPORTED
yarn add typia
yarn typia setup --manager yarn

Terminal

bun add typia
bun typia setup --manager bun

Just run npx typia setup command if you’re using tsc. The setup wizard will do everything.

By the way, if you use typia with bundlers(vite, rollup, webpack, etc), the third party library unplugin-typia is recommended.

Otherwise non-standard compiler case, only the generation mode is available.

Standard Compiler
- Microsoft/TypeScript (tsc)
Non-standard Compilers
- babel
- esbuild -> covered by unplugin-typia
- SWC

Transformation

Concepts

AOT (Ahead of Time) compilation mode.

When you write a TypeScript code calling typia.createIs<IMember>() function and compile it through tsc command, typia will replace the typia.createIs<IMember>() statement to optimal validation code in the compiled JavaScript file, for the IMember type.

This is the transform mode performing AOT (Ahead of Time) compilation.

examples/src/check.ts

import typia, { tags } from "typia";
 
export const check = typia.createIs<IMember>();
 
interface IMember {
  id: string & tags.Format<"uuid">;
  email: string & tags.Format<"email">;
  age: number & tags.ExclusiveMinimum<19> & tags.Maximum<100>;
}

Setup Wizard

Terminal

npm install --save typia
npx typia setup

Terminal

pnpm install --save typia
pnpm typia setup --manager pnpm

Terminal

# YARN BERRY IS NOT SUPPORTED
yarn add typia
yarn typia setup --manager yarn

Terminal

bun add typia
bun typia setup --manager bun

You can turn on transformation mode just by running npx typia setup command.

Setup wizard would be executed, and it will do everything for the transformation.

Manual Setup

Terminal

npm install --save typia
npm install --save-dev typescript ts-patch

Terminal

pnpm install --save typia
pnpm install --save-dev typescript ts-patch

Terminal

# YARN BERRY IS NOT SUPPORTED
yarn add typia
yarn add -D typescript ts-patch

Terminal

bun add typia
bun add -d typescript ts-patch

If you want to install typia manually, just follow the steps.

Firstly install typia as a dependency. And then, install typescript and ts-patch as devDependencies.

tsconfig.json

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

Secondly open your tsconfig.json file as shown above.

As typia generates optimal operation code through transformation, it must be configured as a plugin. Also, never forget to configure strict (or strictNullChecks) to be true within your tsconfig.json compilerOptions. It is essential option for modern TypeScript development.

package.json

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

Terminal

npm run prepare

Terminal

pnpm prepare

Terminal

# YARN BERRY IS NOT SUPPORTED
yarn prepare

Terminal

bun prepare

Finally open package.json file and configure npm run prepare command like above.

Be sure to run npm run prepare once you have made these changes.

For reference, ts-patch is an helper library of TypeScript compiler that supporting custom transformations by plugins. From now on, whenever you run tsc command, your typia function call statements would be transformed to the optimal operation codes in the compiled JavaScript files.

Bundlers

`unplugin-typia`

unplugin-typia is a plugin to integrate typia into your bundlers seamlessly.

Currently, unplugin-typia supports the following bundlers:

Terminal

npx jsr add -D @ryoppippi/unplugin-typia # via jsr (recommended)
# npm install -D @ryoppippi/unplugin-typia # via npm
 
npm install --save typia
npx typia setup

Terminal

pnpm dlx jsr add -D @ryoppippi/unplugin-typia
pnpm install typia
pnpm typia setup --manager pnpm

Terminal

# YARN BERRY IS NOT SUPPORTED
yarn dlx jsr add -D @ryoppippi/unplugin-typia
yarn add typia
yarn typia setup --manager yarn

Terminal

bunx jsr add @ryoppippi/unplugin-typia
bun add typia
bun typia setup

At first, install both unplugin-typia and typia, with npx typia setup command.

After that, follow the next section steps to integrate unplugin-typia into your bundlers.

For reference, there are a couple of ways to integrate unplugin-typia into your bundlers. For the full integration guide, please refer to the unplugin-typia documentation. Also, you can see the examples projects in unplugin-typia repository.

You can use any plugins with unplugin-typia in Vite (including @vitejs/plugin-react-swc). unplugin-typia processes the TypeScript code before transforming it to JavaScript, so it can be used with any plugins.

vite.config.ts

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

next.config.mjs

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

esbuild.config.js

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

First, create a preload.ts file and add the following code.

preload.ts

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

Then, add the preload option to your bunfig.toml file.

bunfig.toml

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

And, run the bun run command.

Terminal

bun run index.ts

For more details, please refer to the unplugin-typia documentation.

Build.ts

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

For more details, please refer to the unplugin-typia documentation.

webpack

unplugin-typia also supports webpack as well.

Terminal

# TYPIA
npm install typia
npx typia setup
 
# WEBPACK + TS-LOADER
npm install --save-dev ts-loader
npm install --save-dev webpack webpack-cli

Terminal

# TYPIA
pnpm install typia
pnpm typia setup --manager pnpm
 
# WEBPACK + TS-LOADER
pnpm install --save-dev ts-loader
pnpm install --save-dev webpack webpack-cli

Terminal

###########################################
# YARN BERRY IS NOT SUPPORTED
###########################################
# TYPIA
yarn add typia
yarn typia setup --manager yarn
 
# WEBPACK + TS-LOADER
yarn add -D ts-loader
yarn add -D webpack webpack-cli

Terminal

# TYPIA
bun add typia
bun typia setup
 
# WEBPACK + TS-LOADER
bun add -d ts-loader
bun add -d webpack webpack-cli

When you’re using webpack as a bundler, you can still utilize the transformation mode.

Just install ts-loader as well as webpack, and configure webpack.config.js file like below.

webpack.config.js

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

From now on, you can build the single JS file just by running the npx webpack command. By the way, when removing devDependencies for --production install, never forget to add the --ignore-scripts option to prevent the prepare script.

Terminal

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

Terminal

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

Terminal

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

Terminal

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

Additionally, if you’re using typia in the NodeJS project especially for the backend development, Setup Guide Documents of nestia would be helpful. Even though you’re not using NestJS, you can still utilize below documents, and “Single JS file only” mode would be especially helpful for you.

Nestia > Setup > Webpack
- With node_modules
- Single JS file only

Nx

Terminal

npm install --save typia
npx typia setup

Terminal

pnpm install --save typia
pnpm typia setup --manager pnpm

Terminal

# YARN BERRY IS NOT SUPPORTED
yarn add typia
yarn typia setup --manager yarn

Terminal

bun add typia
bun typia setup --manager bun

After installing typia like above, and ensuring the prepare script is something similar to ts-patch install you have to modify the tsconfig.lib.json on each @nx/js package to be similar to the below.

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"]
}

After this, when running nx <package-name>:build it should now output with the Typia transforms applied. But if Typia fails for any reasons (for example it considers some type you have to be invalid), this error is not reported back via Nx. Nx will silent swallow these errors from ts-patch/typia, and you will just not get the output you expect. To debug this, you can create a new task in your project.json file similar to the below.

project.json

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

Running this task will show you the errors from Typia, and allow you to correct them, meaning that using the standard nx <package-name>:build task should now work the way you expect.

Note: While Nx has a transformers feature on the @nx/js plugin, that won’t work with Typia. The reason is because Nx is expecting a transformer to export a before hook, which Nx then plugs directly into TypeScript via the compiler API. Typia doesn’t export that kind of hook, because Typia only works with ts-patch, which abstracts the need for creating a specific before hook in the way Nx wants.

Generation

Terminal

# INSTALL TYPIA
npm install --save typia
npm install --save-dev typescript
 
# GENERATE TRANSFORMED TYPESCRIPT CODES
npx typia generate \
  --input src/templates \
  --output src/generated \
  --project tsconfig.json

Terminal

# INSTALL TYPIA
pnpm install --save typia
pnpm install --save-dev typescript
 
# GENERATE TRANSFORMED TYPESCRIPT CODES
pnpm typia generate \
  --input src/templates \
  --output src/generated \
  --project tsconfig.json

Terminal

# INSTALL TYPIA
yarn add typia
yarn add -D typescript
 
# GENERATE TRANSFORMED TYPESCRIPT CODES
yarn typia generate \
  --input src/templates \
  --output src/generated \
  --project tsconfig.json

Terminal

# INSTALL TYPIA
bun add typia
bun add -d typescript
bun typia generate \
  --input src/templates \
  --output src/generated \
  --project tsconfig.json

For frontend projects.

If you are using a non-standard TypeScript compiler such as the following, you will need to fall back to generation mode

Non-standard TypeScript compilers:
- Babel in Create-React-App
- esbuild in Vite -> covered by unplugin-typia
- SWC -> use unplugin-typia with your bundlers ( including next.js, vite, webpack, rollup, etc )

Instead you should utilise the generation mode.

Install typia through npm install command, and run typia generate command. Then, generator of typia reads your TypeScript codes of --input, and writes transformed TypeScript files into the --output directory, like below.

For clarification, the input directory should contain one or more TypeScript files which define how you want to verify your associated type assertions. Commonly you will import your TypeScript type, then export a function which validates that type. See below.

If you want to specify other TypeScript project file instead of tsconfig.json, you can use --project option.

examples/src/templates/check.ts

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

🚫

Why not support non-standard compilers?

Non-standard TypeScript compilers are removing every type informations, and skipping type checkings for rapid compilation. By the way, without those type informations, typia can’t do anything. This is the reason why typia doesn’t support non-standard TypeScript compilers.

🙋🏻‍♂️ Introduction ⛲ Pure TypeScript