{"id":25289,"library":"esbuild-ignore-with-comments-plugin","title":"esbuild-ignore-with-comments-plugin","description":"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.","status":"active","version":"0.3.29","language":"javascript","source_language":"en","source_url":"https://github.com/goldstack/goldstack","tags":["javascript","node","esbuild"],"install":[{"cmd":"npm install esbuild-ignore-with-comments-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-ignore-with-comments-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-ignore-with-comments-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency – the plugin hooks into esbuild's build process.","package":"esbuild","optional":false}],"imports":[{"note":"The package exports a named function, not a default export. The error 'esbuildIgnoreWithCommentsPlugin is not a function' occurs if using default import.","wrong":"const esbuildIgnoreWithCommentsPlugin = require('esbuild-ignore-with-comments-plugin')","symbol":"esbuildIgnoreWithCommentsPlugin","correct":"import { esbuildIgnoreWithCommentsPlugin } from 'esbuild-ignore-with-comments-plugin'"},{"note":"Aliasing the named import to 'plugin' is common, but default import will result in undefined.","wrong":"import plugin from 'esbuild-ignore-with-comments-plugin'","symbol":"plugin","correct":"import { esbuildIgnoreWithCommentsPlugin as plugin } from 'esbuild-ignore-with-comments-plugin'"},{"note":"For TypeScript users, the package exports a type for plugin options.","symbol":"PluginOptions","correct":"import type { PluginOptions } from 'esbuild-ignore-with-comments-plugin'"}],"quickstart":{"code":"import { build } from 'esbuild';\nimport { esbuildIgnoreWithCommentsPlugin } from 'esbuild-ignore-with-comments-plugin';\n\nawait build({\n  entryPoints: ['src/index.ts'],\n  outfile: 'dist/bundle.js',\n  bundle: true,\n  plugins: [esbuildIgnoreWithCommentsPlugin()],\n});","lang":"typescript","description":"Demonstrates basic usage of the plugin with esbuild to ignore files containing a special comment."},"warnings":[{"fix":"Ensure the ignore comment (default: '// esbuild-ignore') is the first line in the file.","message":"The plugin checks for comments at the top of the file only; comments anywhere else will not trigger ignoring.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Update your files to use '// esbuild-ignore' or pass custom comment: esbuildIgnoreWithCommentsPlugin({ comment: '// @ignore' })","message":"Version 0.3.0 changed the default ignore comment from '// @ignore' to '// esbuild-ignore'.","severity":"breaking","affected_versions":">=0.3.0"},{"fix":"For binary files, handle ignoring differently (e.g., via external flag).","message":"The plugin only works with JavaScript/TypeScript files and other text-based files that esbuild processes; binary files like images are not affected.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"import { esbuildIgnoreWithCommentsPlugin } from 'esbuild-ignore-with-comments-plugin'","cause":"Using default import instead of named import.","error":"TypeError: esbuildIgnoreWithCommentsPlugin is not a function"},{"fix":"Ensure the ignore comment is the first line and no other comments appear before it.","cause":"File contains multiple lines of comments before the ignore comment.","error":"Error: [plugin esbuild-ignore-with-comments] Expected a single top-level comment"},{"fix":"Run 'npm install esbuild-ignore-with-comments-plugin' and use correct import.","cause":"Package not installed or import path is incorrect.","error":"Module not found: Error: Can't resolve 'esbuild-ignore-with-comments-plugin'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}