Barcode Writer in Pure JavaScript (bwip-js)

Common errors

• TypeError: bwipjs is not a function

  cause Attempting to use `bwipjs` as a named export when it is a default export, or a CommonJS `require()` for an ESM-only package.
  fix If using ES Modules, ensure `import bwipjs from 'bwip-js';` (for the main package) or `import { namedExport } from '@bwip-js/platform';`. If using CommonJS, use `const bwipjs = require('bwip-js');` for the main package. Do not use `require()` for ESM-only platform packages like `@bwip-js/browser`.

• ReferenceError: document is not defined or ReferenceError: CanvasRenderingContext2D is not defined

  cause Attempting to use browser-specific rendering methods (like `toCanvas()`) or browser-dependent global objects (like `document`) within a Node.js environment without a headless browser or canvas emulation library.
  fix In Node.js, use the `@bwip-js/node` package and its `toBuffer()` method for generating PNG buffers. For browser environments, use `@bwip-js/browser` and `toCanvas()` to render to an HTML canvas element. Ensure you are importing the correct platform-specific package for your target environment.

• BWIP-JS: Unknown BCID

  cause The barcode identifier (`bcid`) provided to the generator function is either misspelled, not supported by the library, or uses an outdated name.
  fix Consult the `bwip-js` documentation or the BWIPP wiki for a complete, case-sensitive list of supported barcode types (BCIDs). Correct the `bcid` parameter to a recognized identifier.

Warnings

• breaking Version 4.9.1 and 4.9.2 addressed a critical bug (#372) that could lead to incorrect barcode generation or runtime errors in specific scenarios. Users on older 4.x versions, especially those before 4.9.1, should upgrade immediately to prevent potential data integrity or display issues.
  Fix: Upgrade to `bwip-js@4.9.2` or higher to incorporate the critical fixes.
• breaking The introduction of platform-specific packages (`@bwip-js/node`, `@bwip-js/browser`, `@bwip-js/react-native`, `@bwip-js/generic`) significantly changed import patterns. `@bwip-js/browser`, `@bwip-js/react-native`, and `@bwip-js/generic` are ES Modules (ESM) only, requiring `import` statements and modern build environments. Only the `@bwip-js/node` package and the main `bwip-js` package retain CommonJS `require()` compatibility for their primary exports.
  Fix: For browser, React Native, or generic platform code, migrate to ES Module `import` syntax and ensure your build tooling supports ESM. For Node.js, you can choose between `require()` or `import` based on your project setup and the specific `bwip-js` package used.
• gotcha Version 4.8.0 introduced new text layout features from BWIPP, including a `font.rotate` property. If you are using a custom drawing interface, you may need to update your drawing object's `text()` method to correctly handle this new property, or text rendering within your barcodes might be misaligned or fail.
  Fix: Review the 'Annotated Example Drawing Object' in the `bwip-js` wiki (linked in the README) and adjust your custom drawing interface to properly manage the `font.rotate` property when it is passed to the `text()` method.
• breaking Versions 4.5.2 and 4.5.3 fixed critical bugs (#354) related to `azteccode` that caused corrupted encoding of binary data. Using `azteccode` with binary input in versions prior to 4.5.2 could result in unreadable or incorrectly generated barcodes.
  Fix: Upgrade to `bwip-js@4.5.3` or higher if you generate Aztec barcodes, especially when encoding binary or non-ASCII data, to ensure correct and reliable output.

Install

• npm install bwip-js npm
• yarn add bwip-js yarn
• pnpm add bwip-js pnpm

Imports

• bwipjs
  wrong:

  import { bwipjs } from 'bwip-js';

  correct:

  import bwipjs from 'bwip-js';

  `bwipjs` is the default export for the main `bwip-js` package when using ES Modules. This import works in both Node.js (ESM) and browser environments, providing a universal entry point for barcode generation functions.
• bwipjs
  wrong:

  const { bwipjs } = require('bwip-js');

  correct:

  const bwipjs = require('bwip-js');

  This is the CommonJS `require()` import for the main `bwip-js` package, compatible with older Node.js versions or CJS-specific projects. The main package includes CJS compatibility.
• toBuffer
  wrong:

  const { toBuffer } = require('@bwip-js/node');

  correct:

  import { toBuffer } from '@bwip-js/node';

  `toBuffer` is a named export from the `@bwip-js/node` package, specifically designed for Node.js environments to generate barcodes as PNG image buffers. While `@bwip-js/node` *also* has CJS support, `import` is the preferred modern approach for its named exports.
• toCanvas
  wrong:

  const { toCanvas } = require('@bwip-js/browser');

  correct:

  import { toCanvas } from '@bwip-js/browser';

  `@bwip-js/browser` is an ES Modules (ESM) only package. `toCanvas` is a named export used in browser environments to render barcodes directly to an HTML canvas element. Attempting to `require()` this package will result in an error.

Quickstart

Demonstrates how to generate a Code 128 barcode as a PNG buffer using the `@bwip-js/node` package and save it to a local file. This showcases basic configuration and file system interaction in Node.js.

import { toBuffer } from '@bwip-js/node';
import { writeFile } from 'fs/promises';
import { resolve } from 'path';

async function generateBarcode() {
  try {
    // Generate a Code 128 barcode with specific properties
    const pngBuffer = await toBuffer({
      bcid: 'code128',     // Barcode type
      text: 'BWIPJS-SAMPLE-123', // Text to encode
      scale: 3,             // 3x scaling factor
      height: 10,           // Bar height, in millimeters
      includetext: true,    // Show human-readable text below the barcode
      textxalign: 'center', // Center the text
      backgroundcolor: 'ffffff', // White background (hex color)
      barcolor: '000000',    // Black bars (hex color)
      padding: 5             // 5mm padding around the barcode
    });

    // Define the output path for the PNG file
    const outputPath = resolve(process.cwd(), 'barcode.png');
    await writeFile(outputPath, pngBuffer);
    console.log(`Barcode generated successfully at ${outputPath}`);
  } catch (e) {
    console.error('Error generating barcode:', e instanceof Error ? e.message : e);
  }
}

generateBarcode();