esbuild-ignore-with-comments-plugin

0.3.29 verified Fri May 01 auth: no javascript

An esbuild plugin that allows developers to exclude specific files from the build by placing a designated comment (e.g., `// esbuild-ignore`) at the top of the file. The current stable version is 0.3.29 and it is part of the Goldstack monorepo. It requires esbuild ^0.25.6 as a peer dependency. Key differentiators: lightweight, zero-config for ignoring files based on comments, and compatible with both ESM and CJS projects.

Common errors

error TypeError: esbuildIgnoreWithCommentsPlugin is not a function ↓

cause Using default import instead of named import.

fix

import { esbuildIgnoreWithCommentsPlugin } from 'esbuild-ignore-with-comments-plugin'

error Error: [plugin esbuild-ignore-with-comments] Expected a single top-level comment ↓

cause File contains multiple lines of comments before the ignore comment.

fix

Ensure the ignore comment is the first line and no other comments appear before it.

error Module not found: Error: Can't resolve 'esbuild-ignore-with-comments-plugin' ↓

cause Package not installed or import path is incorrect.

fix

Run 'npm install esbuild-ignore-with-comments-plugin' and use correct import.

Warnings

gotcha The plugin checks for comments at the top of the file only; comments anywhere else will not trigger ignoring. ↓

fix Ensure the ignore comment (default: '// esbuild-ignore') is the first line in the file.

breaking Version 0.3.0 changed the default ignore comment from '// @ignore' to '// esbuild-ignore'. ↓

fix Update your files to use '// esbuild-ignore' or pass custom comment: esbuildIgnoreWithCommentsPlugin({ comment: '// @ignore' })

gotcha The plugin only works with JavaScript/TypeScript files and other text-based files that esbuild processes; binary files like images are not affected. ↓

fix For binary files, handle ignoring differently (e.g., via external flag).

Install

npm install esbuild-ignore-with-comments-plugin

yarn add esbuild-ignore-with-comments-plugin

pnpm add esbuild-ignore-with-comments-plugin

Imports

esbuildIgnoreWithCommentsPlugin
wrong
```
const esbuildIgnoreWithCommentsPlugin = require('esbuild-ignore-with-comments-plugin')
```
correct
```
import { esbuildIgnoreWithCommentsPlugin } from 'esbuild-ignore-with-comments-plugin'
```
The package exports a named function, not a default export. The error 'esbuildIgnoreWithCommentsPlugin is not a function' occurs if using default import.

plugin

wrong

import plugin from 'esbuild-ignore-with-comments-plugin'

correct

import { esbuildIgnoreWithCommentsPlugin as plugin } from 'esbuild-ignore-with-comments-plugin'

Aliasing the named import to 'plugin' is common, but default import will result in undefined.

PluginOptions
```
import type { PluginOptions } from 'esbuild-ignore-with-comments-plugin'
```
For TypeScript users, the package exports a type for plugin options.

Quickstart

Demonstrates basic usage of the plugin with esbuild to ignore files containing a special comment.

import { build } from 'esbuild';
import { esbuildIgnoreWithCommentsPlugin } from 'esbuild-ignore-with-comments-plugin';

await build({
  entryPoints: ['src/index.ts'],
  outfile: 'dist/bundle.js',
  bundle: true,
  plugins: [esbuildIgnoreWithCommentsPlugin()],
});