esbuild-preserve-whitespace

1.1.1 verified Fri May 01 auth: no javascript

An esbuild plugin that preserves blank lines and whitespace during TypeScript transpilation. Version 1.1.1 requires esbuild ^0.19.0 and the legalComments: 'inline' option. It works by replacing blank lines with marker comments before esbuild processes files, then removing them after. Unlike esbuild's default behavior (which strips most whitespace), this plugin provides configurable preservation of formatting, useful for debugging, code review, or when output readability matters. The plugin is lightweight, typed (TypeScript), and maintained on GitHub. It has no runtime dependencies beyond esbuild.

Common errors

error Error: The plugin 'esbuild-preserve-whitespace' requires 'legalComments' to be set to 'inline'. ↓

cause legalComments not set or set to a value other than 'inline' in esbuild options.

fix

Add 'legalComments: "inline"' to your esbuild configuration object.

error TypeError: esbuildPreserveWhitespacePlugin is not a function ↓

cause Incorrect import: using require() in CJS context or importing default instead of named export.

fix

Use 'import { esbuildPreserveWhitespacePlugin } from 'esbuild-preserve-whitespace'' or 'const { esbuildPreserveWhitespacePlugin } = await import('esbuild-preserve-whitespace')'.

error Error: Cannot find module 'esbuild-preserve-whitespace' ↓

cause Package not installed or not in node_modules.

fix

Run 'npm install -D esbuild-preserve-whitespace' or equivalent for your package manager.

Warnings

breaking legalComments must be set to 'inline' or plugin will silently fail ↓

fix Add 'legalComments: "inline"' to esbuild options. Without it, marker comments used to preserve whitespace are removed.

gotcha Plugin modifies source files temporarily; if the build crashes, source files may remain altered ↓

fix Ensure build process handles errors (e.g., try/catch) and consider using a clean working directory. The plugin restores files on success but not on failure.

gotcha Only works with files processed by esbuild; does not affect non-esbuild outputs or external files ↓

fix No fix; this is by design. Plugin operates on esbuild's onLoad callback; other files are untouched.

deprecated v1.0.0 had incomplete error handling ↓

fix Upgrade to v1.1.0 or later which includes improved error recovery.

Install

npm install esbuild-preserve-whitespace

yarn add esbuild-preserve-whitespace

pnpm add esbuild-preserve-whitespace

Imports

esbuildPreserveWhitespacePlugin

wrong

const esbuildPreserveWhitespacePlugin = require('esbuild-preserve-whitespace')

correct

import { esbuildPreserveWhitespacePlugin } from 'esbuild-preserve-whitespace'

Package is ESM-only; CommonJS require() will fail. Use dynamic import() if needed in CJS.

PluginOptions
wrong
```
import { PluginOptions } from 'esbuild-preserve-whitespace'
```
correct
```
import type { PluginOptions } from 'esbuild-preserve-whitespace'
```
PluginOptions is a type export; use 'import type' to avoid runtime issues. Available as named type export.
default import
```
import esbuildPreserveWhitespacePlugin from 'esbuild-preserve-whitespace'
```
Default export is not provided; only named export exists. Attempting default import will result in undefined.

Quickstart

Basic esbuild build with whitespace preservation plugin. Note that legalComments: 'inline' is mandatory.

import { esbuildPreserveWhitespacePlugin } from 'esbuild-preserve-whitespace';
import * as esbuild from 'esbuild';

await esbuild.build({
  entryPoints: ['src/index.ts'],
  outfile: 'dist/index.js',
  bundle: true,
  legalComments: 'inline', // Required
  plugins: [
    esbuildPreserveWhitespacePlugin({
      verbose: false,
    }),
  ],
});