esbuild import assertions plugin

1.0.1 verified Fri May 01 auth: no javascript

A plugin for esbuild that enables import assertion syntax (e.g. `import json from './foo.json' assert { type: 'json' }`) in your builds. Current stable version is 1.0.1. This plugin adds the ability to use the TC39 proposal for import assertions, which esbuild does not natively support. It works only with synchronous imports and requires `bundle: true`. Key differentiator: it fills a gap for users who need import assertions without switching to a different bundler like Webpack or Rollup.

Common errors

error Error: The package "esbuild-plugin-import-assertions" is not a CommonJS module, use dynamic import() instead. ↓

cause Attempting to require the package in a CommonJS environment without using dynamic import.

fix

Use import() or change the project to ESM (type: 'module' in package.json).

error TypeError: importAssertPlugin is not a function ↓

cause Importing the default export instead of the named export 'importAssertPlugin'.

fix

Use named import: import { importAssertPlugin } from 'esbuild-plugin-import-assertions';

error Error: Import assertions are not supported with dynamic imports ↓

cause Using dynamic import() with import assertions, which the plugin does not support.

fix

Convert to static import statements.

Warnings

gotcha Asynchronous imports are not supported. Only static import statements with assertions will be handled. ↓

fix Rewrite dynamic import() calls with assertions as static imports if possible, or use an alternative approach.

gotcha The plugin requires that esbuild's 'bundle' option is set to true. Without it, the plugin will not transform imports. ↓

fix Set 'bundle: true' in the esbuild options.

Install

npm install esbuild-plugin-import-assertions

yarn add esbuild-plugin-import-assertions

pnpm add esbuild-plugin-import-assertions

Imports

importAssertPlugin
wrong
```
const { importAssertPlugin } = require('esbuild-plugin-import-assertions')
```
correct
```
import { importAssertPlugin } from 'esbuild-plugin-import-assertions'
```
The package exports a named export, not a default. CommonJS require will not work as the package is ESM-only. Use dynamic import() if needed in CJS.
default export
wrong
```
import importAssertPlugin from 'esbuild-plugin-import-assertions'
```
correct
```
Not available. Use named import.
```
There is no default export. Attempting to import it as default will result in undefined.

Quickstart

Demonstrates basic esbuild build with the import assertions plugin, requiring bundle: true.

import { importAssertPlugin } from 'esbuild-plugin-import-assertions';
import { build } from 'esbuild';

build({
  entryPoints: ['./app.ts'],
  bundle: true,
  outfile: './lib/out.js',
  plugins: [importAssertPlugin],
  target: ['chrome100']
}).catch(() => process.exit(1));