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 from 'typegpu';
  import * as d from 'typegpu/data';
  
  // 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, the exported plugin needs to be included in the list of plugins in the bundler config.

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'],
  };
};

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.