Summary

npm install typia
npx typia setup

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 (opens in a new tab) (tsc)
• Non-standard Compilers
  • babel (opens in a new tab)
  • esbuild (opens in a new tab) -> covered by unplugin-typia
  • SWC (opens in a new tab)

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.

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

npm install --save typia
npx typia setup

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

npm install --save typia
npm install --save-dev 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.

{
  "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.

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

npm run 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 (opens in a new tab) 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 (opens in a new tab) is a plugin to integrate typia into your bundlers seamlessly.

Currently, unplugin-typia supports the following bundlers:

• Bun (opens in a new tab)
• Esbuild (opens in a new tab)
• Farm (opens in a new tab)
• Next.js (opens in a new tab)
• Rolldown (opens in a new tab)
• Rollup (opens in a new tab)
• Rspack (opens in a new tab)
• Vite (opens in a new tab)
• Webpack (opens in a new tab)

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

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 (opens in a new tab). Also, you can see the examples projects in unplugin-typia repository (opens in a new tab).

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

webpack

# TYPIA
npm install typia
npx typia setup
 
# WEBPACK + TS-LOADER
npm install --save-dev ts-loader
npm install --save-dev 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.

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.

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

Additionally, if you're using typia in the NodeJS project especially for the backend development, Setup Guide Documents of nestia (opens in a new tab) 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 (opens in a new tab)
  • With node_modules (opens in a new tab)
  • Single JS file only (opens in a new tab)

NX

npm install --save typia
npx typia setup

After install typia like above, you have to modify project.json on each app like below.

 "targets": {
    "build": {
      ...
      "options": {
        ...
        "target": "node",
        "compiler": "tsc",
        "transformers": [
          "typia/lib/transform",
        ]
      }
    },
    ...
 }

Generation

# 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

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 (opens in a new tab) in Create-React-App
  • esbuild (opens in a new tab) in Vite -> covered by unplugin-typia
  • SWC (opens in a new tab) -> 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.

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