unplugin-typia

unplugin for Typia

Why

Typia is fantastic, but it is hard to setup, even for frontend development. If you use some bundlers for frontend like Vite, it is even harder to setup. This unplugin aims to make it easier to use Typia in your projects.

Install

First, install unplugin-typia:

# jsr(recommended)
npx jsr add -D @ryoppippi/unplugin-typia

# npm
npm install -D @ryoppippi/unplugin-typia

Then, install typia:

# install typia! (nypm detects your PM ✨)
npx nypm add typia

# setup typia!
npx typia setup
# pnpm dlx typia setup
# yarn dlx typia setup

# after installing typia, run prepare script
npm run prepare

More details about setting up Typia can be found in the Typia Docs.

Then, add the unplugin to your favorite bundler:

// vite.config.ts
import UnpluginTypia from '@ryoppippi/unplugin-typia/vite';

export default defineConfig({
	plugins: [
		UnpluginTypia({ /* options */ }), // should be placed before other plugins like `react`, `svetle`, etc.
	],
});

When using typia with types imported from non-relative paths like tsconfig compilerOptions.paths or relative to tsconfig compilerOptions.baseUrl, they must be defined in vite.config.ts under resolve.alias in order to be resolved, according to vite's resolution mechanism.

Examples:

• examples/vite-react
• examples/vite-hono
• examples/sveltekit

// esbuild.config.js
import UnpluginTypia from '@ryoppippi/unplugin-typia/esbuild';

export default {
	plugins: [
		UnpluginTypia({ /* options */ }),
	],
};

Examples:

• tests/rollup.spec.ts

// next.config.mjs
import unTypiaNext from 'unplugin-typia/next';

/** @type {import('next').NextConfig} */
const nextConfig = { /* your next.js config */};

/** @type {import("unplugin-typia").Options} */
const unpluginTypiaOptions = { /* your unplugin-typia options */ };

export default unTypiaNext(nextConfig, unpluginTypiaOptions);

// you can omit the unplugin-typia options when you don't need to customize it
// export default unTypiaNext(nextConfig);

Examples:

• examples/nextjs

Example 1: Using for building script

// build.ts
import UnpluginTypia from '@ryoppippi/unplugin-typia/bun';

await Bun.build({
	entrypoints: ['./index.ts'],
	outdir: './out',
	plugins: [
		UnpluginTypia({ /* your options */})
	]
});

For building the script:

bun run ./build.ts
node ./out/index.js

Check the Plugins – Bundler | Bun Docs for more details.

Example 2: Using for running script

// preload.ts
import { plugin } from 'bun';
import UnpluginTypia from '@ryoppippi/unplugin-typia/bun';

plugin(UnpluginTypia({ /* your options */}));

# bun.toml
preload = "preload.ts"

[test]
preload = "preload.ts"

For running the script:

bun run ./index.ts

Check the Plugins – Runtime | Bun Docs for more details.

// rollup.config.js
import UnpluginTypia from '@ryoppippi/unplugin-typia/rollup';

export default {
	plugins: [
		UnpluginTypia({ /* options */ }),
	],
};

Examples:

• tests/rollup.spec.ts

⚠️ Note: Currently, this plugin works only with 'esm' target.

If you want to use 'cjs' target on Node < 20.17.0 , please use with jiti. If you want to use 'cjs' target on Node >= 20.17.0, please use with require and enable --experimental-require-modules flag. If you want to use 'esm' target, don't worry! You can use this plugin without any additional setup.

npm install jiti

// webpack.config.js

// if you use Node < 20.17.0
const jiti = require('jiti')(__filename);
const { default: UnpluginTypia } = jiti('@ryoppippi/unplugin-typia/webpack');

// if you use Node >= 20.17.0
// const { default: UnpluginTypia } = require("@ryoppippi/unplugin-typia/webpack");

module.exports = {
	plugins: [
		UnpluginTypia({ /* options */ }),
	],
};

More integration guides can be found in the JSR Doc

You can find examples in the examples/.

Supported File Extensions

• .ts
• .tsx
• .mts
• .mtsx
• .svelte (only script tag with lang="ts")

Development

This repository is a monorepo managed by Bun.

• unplugin-typia
• examples

bun i --frozen-lockfile

Acknowledgements

This project started as an unofficial integration of Typia for bundlers. Now, this plugin is one of the official integrations of Typia and is sponsored by @samchon (the creator of Typia).

LICENSE

MIT