Build Plugin

unplugin-typegpu is an optional (but highly recommended) tool for projects using TypeGPU. It hooks into your bundler of choice, and unlocks new features, optimizations and quality-of-life improvements.

The package includes the following functionalities:

• TypeGPU functions implemented in JS/TS

  The plugin allows transpiling a subset of JavaScript to WebGPU Shading Language (WGSL). The parsing of JavaScript happens ahead of time, emitting a highly compact AST format, called tinyest.

  import { tgpu, d } from 'typegpu';
  
  // Found by the plugin and decorated with 'tinyest' metadata
  const add = (a: number, b: number) => {
    'use gpu';
    return a + b;
  };

  Besides parsing JS into an AST, the plugin also collects external references, so it is not necessary to pass them to the $uses method (as is required when implementing functions in WGSL).

• Automatic naming of tgpu objects

  Naming TypeGPU resources via the $name method is very helpful for debugging, but it can get very repetitive. Instead, the plugin is able to automatically name each resource based on the variable names that they are assigned to.

Installation

npm

npm install --save-dev unplugin-typegpu

pnpm

pnpm add -D unplugin-typegpu

yarn

yarn add -D unplugin-typegpu

After installing the package, add the plugin to your bundler config or register it with your runtime using one of the setups below.

Supported bundlers

The plugin was built using unplugin, which allows it to be used with a variety of bundlers. Currently, the package exports plugins for the following ones: esbuild, farm, rolldown, rollup, rspack, vite, webpack. Apart from the tools supported by unplugin, a babel plugin was also created.

Caution

The babel and vite/rollup plugins are the ones that are actively being maintained and tested by the TypeGPU team, the stability of the other ones may be limited.

• Vite

vite.config.js

import { defineConfig } from 'vite';
import typegpuPlugin from 'unplugin-typegpu/vite';

export default defineConfig({
  plugins: [typegpuPlugin()],
});

• Babel (React Native)

babel.config.js

module.exports = (api) => {
  api.cache(true);
  return {
    presets: ['babel-preset-expo'],
    plugins: ['unplugin-typegpu/babel'],
  };
};

Node.js and Deno

Node.js 22.15+ and Deno 2.8+ support synchronous module hooks, so TypeScript shaders can be transformed without a bundler. unplugin-typegpu/node exports the installer; unplugin-typegpu/deno is an alias for the same function.

preload.mjs

import install from 'unplugin-typegpu/node';

const hooks = install(); // Accepts the plugin options below.

# Node.js
node --import ./preload.mjs main.ts

# Deno
deno run --import ./preload.mjs main.ts

The hooks transform subsequently loaded .ts, .js, .mts, .mjs, .cts, and .cjs modules, including CommonJS modules loaded with require(). Deno also handles .jsx and .tsx files. Node.js needs an additional JSX loader for these files: the TypeGPU plugin transforms shaders but does not compile JSX. Node.js’s native TypeScript support handles erasable syntax by default and does not use tsconfig.json. Call hooks.deregister() to remove the hooks.

You can also call install() directly in your entry module, followed by await import('./main.ts'). Use a dynamic import in that case: static imports in the module calling install() are loaded before the hooks are installed. Already loaded modules are not transformed retroactively.

See the Node.js module hooks documentation and Deno loader hooks documentation for more about runtime hooks.

Bun

Register the Bun plugin in a preload module so it runs before your application is loaded:

preload.ts

import { plugin } from 'bun';
import typegpu from 'unplugin-typegpu/bun';

await plugin(typegpu());

bun --preload ./preload.ts main.ts

Alternatively, configure the preload in bunfig.toml and run bun main.ts:

bunfig.toml

preload = ["./preload.ts"]

# Also register the plugin when running `bun test`.
[test]
preload = ["./preload.ts"]

For bundling, pass the plugin directly to Bun.build:

build.ts

import typegpu from 'unplugin-typegpu/bun';

await Bun.build({
  entrypoints: ['./main.ts'],
  outdir: './dist',
  plugins: [typegpu()],
});

The Bun plugin accepts a single regular expression for include; arrays, glob patterns, and exclude are unsupported. By default, it skips files without typegpu, tgpu, or a 'use gpu' directive. Set earlyPruning: false to disable this optimization.

Plugin options

interface Options {
  /** @default [/\.m?[jt]sx?$/] */
  include?: FilterPattern;
  /** @default undefined */
  exclude?: FilterPattern;
  /** @default undefined */
  enforce?: 'post' | 'pre' | undefined;
  /** @default undefined */
  forceTgpuAlias?: string;
  /** @default true */
  autoNamingEnabled?: boolean;

  /**
   * Skipping files that don't contain 'typegpu', 'tgpu' or 'use gpu'.
   * In case this early pruning hinders transformation, you
   * can disable it.
   *
   * @default true
   */
  earlyPruning?: boolean | undefined;
}

The plugin accepts the standard unplugin options, that make it possible to customize which files are to be processed (include/exclude patterns), or enforce the order in which the plugin is run in regards to other plugins.

The custom forceTgpuAlias option allows specifying the name of tgpu object imported from typegpu. It is only useful in a handful of custom scenarios, when the name cannot be retrieved by the plugin automatically from the import statement.

Further reading

For more information about bundler plugins, please refer to the unplugin and babel documentations.