esbuild-plugin-transform

0.5.0 verified Mon Apr 27 auth: no javascript

A plugin for esbuild that enables piping through transformation plugins, compatible with existing esbuild plugins. Version 0.5.0 is current, released in early 2024. It addresses a gap in esbuild's plugin system (issue #1902) by allowing chaining of transforms similar to pipe operations. Key differentiator from alternatives like esbuild-plugin-pipe is TypeScript support and simpler API. Requires Node >=16.14.0. Active development with weekly releases.

Common errors

error Cannot find module 'esbuild-plugin-transform' ↓

cause Package not installed or missing from node_modules.

fix

Run npm install esbuild-plugin-transform

error Transform is not a function ↓

cause Using default import in CommonJS context.

fix

Use import { Transform } from 'esbuild-plugin-transform' instead of require.

error TypeError: Cannot destructure property 'plugins' of 'undefined' or 'null' ↓

cause Calling Transform() without arguments or with incorrect signature.

fix

Use Transform({ plugins: [] }) with an object containing plugins array.

Warnings

breaking The plugin only supports ESM imports. Using require() will fail with 'ERR_REQUIRE_ESM'. ↓

fix Use import statements or dynamic import('/path/to/package').

breaking esbuild must be installed as a dependency with version ^0.17.0 or higher. ↓

fix Install esbuild: npm install esbuild@^0.17.0

gotcha The Transform callback receives an options object, not individual arguments. Using old signature will cause undefined errors. ↓

fix Use Transform({ plugins: [...] }) not Transform(plugins).

gotcha Plugins inside Transform must have `setup` function; others will be silently ignored. ↓

fix Ensure each plugin object has a setup method.

Install

npm install esbuild-plugin-transform

yarn add esbuild-plugin-transform

pnpm add esbuild-plugin-transform

Imports

Transform

wrong

const Transform = require('esbuild-plugin-transform')

correct

import { Transform } from 'esbuild-plugin-transform'

ESM-only. CommonJS require is not supported.

Transform

wrong

import { default as Transform } from 'esbuild-plugin-transform'

correct

import Transform from 'esbuild-plugin-transform'

Default export is the same as named export; both work but named is preferred.

type TransformOptions
```
import type { TransformOptions } from 'esbuild-plugin-transform'
```
TypeScript users should use type import for options type.

Quickstart

Demonstrates using the Transform plugin to wrap an esbuild plugin that logs each transformed file.

import { build } from 'esbuild'
import { Transform } from 'esbuild-plugin-transform'

build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/index.js',
  plugins: [
    Transform({
      plugins: [
        {
          name: 'log-transform',
          setup(build) {
            build.onLoad({ filter: /\.ts$/ }, async (args) => {
              console.log('Transforming:', args.path)
              return undefined
            })
          },
        },
      ],
    }),
  ],
}).catch(() => process.exit(1))