esbuild-plugin-pino

2.3.3 verified Mon Apr 27 auth: no javascript

esbuild-plugin-pino is an esbuild plugin that enables bundling Pino (v7+) with applications by generating extra files required by Pino's worker-thread-based transport architecture. Current stable version is 2.3.3, released regularly with dependency updates. Unlike naive bundling attempts that break Pino's runtime, this plugin automatically produces thread-stream.js, pino-worker.js, pino-pipeline-worker.js, pino-file.js, and any custom transport bundles alongside your main output. It supports ESM and CJS, ships TypeScript types, and requires esbuild 0.25.0–0.25.8, pino >=7, plus optional pino-pretty and thread-stream as peer dependencies.

Common errors

error Error: Cannot find module 'pino-worker.js' ↓

cause The plugin-generated worker file is missing in the deployment directory.

fix

Copy the entire outdir (including all generated files) to production. Ensure the path matches esbuild's outdir.

error Error: The plugin "esbuild-plugin-pino" requires esbuild version >=0.25.0 <=0.25.8 but you have version 0.24.0 ↓

cause Installed esbuild version is outside the plugin's peer dependency range.

fix

Run npm install esbuild@0.25.0 (or compatible) and ensure esbuild-plugin-pino version matches.

error Error [ERR_REQUIRE_ESM]: require() of ES Module esbuild-plugin-pino not supported ↓

cause Using CommonJS require() on an ESM-only version of the plugin (pre-2.3.3).

fix

Use dynamic import() or switch to ESM. Or update to esbuild-plugin-pino >=2.3.3 which supports both.

error TypeError: esbuildPluginPino is not a function ↓

cause Default import used incorrectly; the plugin may be imported as named export in older versions.

fix

Use import esbuildPluginPino from 'esbuild-plugin-pino' (default) or const { esbuildPluginPino } = require('esbuild-plugin-pino').

Warnings

breaking esbuild peer dependency range is strict: esbuild >=0.25.0 <=0.25.8. Using esbuild outside this range may cause plugin failures. ↓

fix Update to esbuild-plugin-pino >=2.3.0 or pin esbuild to a compatible version.

gotcha Extra files (thread-stream.js, pino-worker.js, pino-pipeline-worker.js, pino-file.js) are generated in outdir. These must be included in deployment; missing them causes runtime errors. ↓

fix Ensure all generated files are copied to production. Use the same outdir structure.

deprecated pino-pipeline-worker.js is no longer required after Pino v9.1.0. It may still be generated but is unnecessary. ↓

fix Update to Pino >=9.1.0 or ignore the extra file.

gotcha Yarn PnP users must add package extensions in .yarnrc.yml for pino, pino-pretty, and thread-stream. ↓

fix Add the packageExtensions block shown in README to .yarnrc.yml.

breaking The plugin output changed between v1.x and v2.x; upgrade may require adjusting deployment scripts for generated files. ↓

fix Follow migration guide: update plugin options and ensure all extra files are re-generated.

Install

npm install esbuild-plugin-pino

yarn add esbuild-plugin-pino

pnpm add esbuild-plugin-pino

Imports

default
wrong
```
const esbuildPluginPino = require('esbuild-plugin-pino').default
```
correct
```
import esbuildPluginPino from 'esbuild-plugin-pino'
```
Plugin provides both ESM default export and CJS module.exports. The require pattern shown is also correct but avoids potential .default issue in mixed environments.
esbuildPluginPino (named)
wrong
```
import pinoPlugin from 'esbuild-plugin-pino'
```
correct
```
import { esbuildPluginPino } from 'esbuild-plugin-pino'
```
Named export available since v2.3.3. Using a different name like pinoPlugin still works but may cause confusion.

type PluginOptions

wrong

import { PluginOptions } from 'esbuild-plugin-pino'

correct

import type { PluginOptions } from 'esbuild-plugin-pino'

PluginOptions is a TypeScript type; use type-only import to avoid runtime inclusion.

require (CommonJS)
wrong
```
const pino = require('esbuild-plugin-pino')
```
correct
```
const esbuildPluginPino = require('esbuild-plugin-pino')
```
CommonJS require works as plugin exports a single function. Avoid naming it 'pino' to prevent confusion with the pino logger.

Quickstart

Shows basic usage: import plugin, pass it to esbuild build with transports option, and use pino logger with that transport at runtime.

// esbuild build script with pino plugin
import { build } from 'esbuild';
import esbuildPluginPino from 'esbuild-plugin-pino';

await build({
  entryPoints: ['src/index.ts'],
  outdir: 'dist',
  bundle: true,
  plugins: [esbuildPluginPino({ transports: ['pino-pretty'] })],
});

// Then in your application:
import pino from 'pino';
const logger = pino({
  transport: {
    target: 'pino-pretty',
    options: { colorize: true }
  }
});
logger.info('Hello from bundled app!');