{"id":15089,"library":"bwip-js","title":"Barcode Writer in Pure JavaScript (bwip-js)","description":"bwip-js is a JavaScript library that provides a comprehensive barcode generation solution, translating the Barcode Writer in Pure PostScript (BWIPP) code into native JavaScript. It supports over 100 different barcode types and standards, including all common linear and two-dimensional formats. The library is currently at version 4.9.2, with its underlying BWIPP engine updated to 2026-03-31. Releases are frequent, typically coinciding with BWIPP updates or critical bug fixes, as seen with recent rapid patches for version 4.9.x. It differentiates itself by offering broad platform support (browsers, Node.js, React, React Native, Electron) and output formats (PNG, Canvas, SVG), and by being a pure JavaScript implementation requiring no external binaries or server-side rendering other than a JavaScript runtime.","status":"active","version":"4.9.2","language":"javascript","source_language":"en","source_url":"https://github.com/metafloor/bwip-js","tags":["javascript","bar code","generator","barcode","node","react","react-native","typescript"],"install":[{"cmd":"npm install bwip-js","lang":"bash","label":"npm"},{"cmd":"yarn add bwip-js","lang":"bash","label":"yarn"},{"cmd":"pnpm add bwip-js","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"`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.","wrong":"import { bwipjs } from 'bwip-js';","symbol":"bwipjs","correct":"import bwipjs from 'bwip-js';"},{"note":"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.","wrong":"const { bwipjs } = require('bwip-js');","symbol":"bwipjs","correct":"const bwipjs = require('bwip-js');"},{"note":"`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.","wrong":"const { toBuffer } = require('@bwip-js/node');","symbol":"toBuffer","correct":"import { toBuffer } from '@bwip-js/node';"},{"note":"`@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.","wrong":"const { toCanvas } = require('@bwip-js/browser');","symbol":"toCanvas","correct":"import { toCanvas } from '@bwip-js/browser';"}],"quickstart":{"code":"import { toBuffer } from '@bwip-js/node';\nimport { writeFile } from 'fs/promises';\nimport { resolve } from 'path';\n\nasync function generateBarcode() {\n  try {\n    // Generate a Code 128 barcode with specific properties\n    const pngBuffer = await toBuffer({\n      bcid: 'code128',     // Barcode type\n      text: 'BWIPJS-SAMPLE-123', // Text to encode\n      scale: 3,             // 3x scaling factor\n      height: 10,           // Bar height, in millimeters\n      includetext: true,    // Show human-readable text below the barcode\n      textxalign: 'center', // Center the text\n      backgroundcolor: 'ffffff', // White background (hex color)\n      barcolor: '000000',    // Black bars (hex color)\n      padding: 5             // 5mm padding around the barcode\n    });\n\n    // Define the output path for the PNG file\n    const outputPath = resolve(process.cwd(), 'barcode.png');\n    await writeFile(outputPath, pngBuffer);\n    console.log(`Barcode generated successfully at ${outputPath}`);\n  } catch (e) {\n    console.error('Error generating barcode:', e instanceof Error ? e.message : e);\n  }\n}\n\ngenerateBarcode();\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade to `bwip-js@4.9.2` or higher to incorporate the critical fixes.","message":"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.","severity":"breaking","affected_versions":"<4.9.1"},{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.8.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"<4.5.2"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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`.","cause":"Attempting to use `bwipjs` as a named export when it is a default export, or a CommonJS `require()` for an ESM-only package.","error":"TypeError: bwipjs is not a function"},{"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.","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.","error":"ReferenceError: document is not defined or ReferenceError: CanvasRenderingContext2D is not defined"},{"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.","cause":"The barcode identifier (`bcid`) provided to the generator function is either misspelled, not supported by the library, or uses an outdated name.","error":"BWIP-JS: Unknown BCID"}],"ecosystem":"npm"}