Setup

Summary

npm install typia
npx typia setup

If you're using standard TypeScript compiler, you can use transform mode.

Just run npx typia setup command, then everything be prepared.

• Standard TypeScript Compiler: Microsoft/TypeScript (opens in a new tab)

npm install typia
npm install --save-dev typescript
 
npx typia generate \
  --input src/templates \
  --output src/generated \
  --project tsconfig.json

Otherwise you are using non-standard TypeScript compiler, then you can't use transformation mode.

Instead, you can use generation mode.

Run typia generate command with input directory, then transformed TypeScript files would be generated into the output directory.

• Non-standard TypeScript Compilers
  • SWC (opens in a new tab)
  • ESBuild (opens in a new tab)
  • Babel (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 ts-node

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

At first, install typia as dependency. And then, install typescript, ts-patch and ts-node as devDependencies.

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

At second, open your tsconfig.json file and configure like above.

As typia generates optimal operation code through transformation, you've to configure it as a plugin. Also, never forget to configure strict (or strictNullChecks) to be true. It is essential option for modern TypeScript development.

{
  "scripts": {
    "prepare": "ts-patch install && typia patch"
  },
  "dependencies": {
    "typia": "^4.1.8"
  },
  "devDependencies": {
    "ts-node": "^10.9.1",
    "ts-patch": "^3.0.2",
    "typescript": "^5.1.6"
  }
}

npm run prepare

At last, open package.json file and configure npm run prepare command like above.

Of course, you've to run the npm run prepare command after the configuration.

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.

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're using non-standard TypeScript compiler, you can't use transform mode

• Non-standard TypeScript compilers:
  • SWC (opens in a new tab) in Next.JS
  • ESBuild (opens in a new tab) in Vite
  • Babel (opens in a new tab) in Create-React-App

Instead, you should utilize 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.

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>();

Vite

If you've made your frontend project through vite, you can still utilize the transformation mode.

Just configure vite.config.ts file below, that's all.

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import typescript from "rollup-plugin-typescript2";
 
// https://vitejs.dev/config/
export default defineConfig({
  esbuild: false,
  plugins: [
    react(),
    typescript(),
  ],
});

By the way, if you're composing monorepo, and need to import some external TypeScript files from the other package of the monorepo, you've to configure the vite.config.ts a little bit different. When declaring typescript plugin, you've to specify include and exclude options like below.

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import typescript from "rollup-plugin-typescript2";
 
// https://vitejs.dev/config/
export default defineConfig({
  esbuild: false,
  plugins: [
    react(),
    typescript({
      // WHEN MONOREPO
      include: [
        "./**/*.ts+(|x)",
        "../../core/**/*.ts+(|x)",
        "../../util/**/*.ts+(|x)",
      ],
      exclude: ["../../node_modules"],
    }),
  ],
});

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