// Barcode Writer in Pure JavaScript

bwip-js is a translation to native JavaScript of the amazing code provided in Barcode Writer in Pure PostScript. The translated code can run on any modern browser or JavaScript-based server framework.

The software has encoding modules for over 90 different barcode types and standards. All linear and two-dimensional barcodes in common use (and many uncommon ones) are available. An exhaustive list of supported barcode types can be found at the end of this document.

bwip-js has finally hit the 1.0 release. This release uses a newly developed optimizing PostScript to JavaScript cross-compiler that reduces code size and improves performance, in some cases an order-of-magnitude decrease in run time. See the Version 1.0 Release Announcement for more details.

Version 1.0 is an API breaking release. If you are using the demo or the Node.js module without modification, there is no change. If you have customized the node module or integrated bwip-js into your code directly, you will need to make some adjustments.

The new JavaScript API is significantly simplified. Asynchronous module loading has been eliminated. You simply load or require() three modules (FreeType, BWIPP, and bwip-js) rather than having to create separate execution contexts and asynchronously load into them.

See Integrating With Your Code for more details.

Status

• Current bwip-js version is 1.3.2 (2017-04-11)
• Current BWIPP version is 2017-04-04
• Node.js compatibility >= v0.10

Links

• Home Page
• Repository
• Online Barcode Generator
• Online Barcode API
• Node.js npm Page
• BWIPP Documentation
• Differences between BWIPP and bwipjs
• Supported Barcode Types

Online Barcode Generator

An online barcode generator demonstrates all of the features of bwip-js. All features and options of BWIPP are available, along with the font rendering provided by the FreeType library. It also allows using your own fonts. The fonts are stored locally on your computer; the demo is 100% client-side JavaScript.

The demo is tested on the latest versions of Firefox and Chrome, along with IE10 and IE11. Microsoft Edge should work, and so should the latest versions of Opera and Safari, but they are untested.

Online Barcode API

A bwip-js barcode service is available online, ready to serve up barcode images on demand.

You can generate barcodes from anywhere on the web. Embed the URLs in your HTML documents or retrieve the barcode images directly from your non-JavaScript server. (JavaScript-based servers should use the bwip-js code directly - it will be a lot more performant.)

For details on how to use this service, see Online Barcode API.

Node.js Request Handler

The online barcode API is implemented as a Node.js application. The code used for the service is available as part of the bwip-js source code. See the Online Barcode API for details on how the URL query parameters must be structured.

A working, minimal example of how to use the request handler can be found in server.js:

// Simple HTTP server that renders barcode images using bwip-js.
var http   = require('http');
var bwipjs = require('bwip-js');

// Example of how to load a font into bwipjs. 
//    bwipjs.loadFont(fontname, sizemult, fontdata)
//
// To unload a font (and free up space for another):
//    bwipjs.unloadFont(fontname)
//
bwipjs.loadFont('Inconsolata', 108,
            require('fs').readFileSync('fonts/Inconsolata.otf', 'binary'));

http.createServer(function(req, res) {
    // If the url does not begin /?bcid= then 404.  Otherwise, we end up
    // returning 400 on requests like favicon.ico.
    if (req.url.indexOf('/?bcid=') != 0) {
        res.writeHead(404, { 'Content-Type':'text/plain' });
        res.end('BWIPJS: Unknown request format.', 'utf8');
    } else {
        bwipjs(req, res);
    }

}).listen(3030);

If you run the above code on your local machine, you can test with the following URL:

http://localhost:3030/?bcid=isbn&text=978-1-56581-231-4+52250&includetext&guardwhitespace

The bwip-js request handler only operates on the URL query parameters and ignores all path information. Your application is free to structure the URL path as needed to implement the desired HTTP request routing.

Node.js Image Generator

You can also use bwip-js to generate PNG images directly.

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

// Optionally load some custom fonts.  Maximum 8.
// OpenType and TrueType are supported.
bwipjs.loadFont('Inconsolata', 108,
            require('fs').readFileSync('fonts/Inconsolata.otf', 'binary'));

bwipjs.toBuffer({
        bcid:        'code128',       // Barcode type
        text:        '0123456789',    // Text to encode
        scale:       3,               // 3x scaling factor
        height:      10,              // Bar height, in millimeters
        includetext: true,            // Show human-readable text
        textxalign:  'center',        // Always good to set this
        textfont:    'Inconsolata',   // Use your custom font
        textsize:    13               // Font size, in points
    }, function (err, png) {
        if (err) {
            // Decide how to handle the error
            // `err` may be a string or Error object
        } else {
            // `png` is a Buffer
            // png.length           : PNG file length
            // png.readUInt32BE(16) : PNG image width
            // png.readUInt32BE(20) : PNG image height
        }
    });

Only the first two options bcid and text are required. The other bwip-js specific options are:

• scaleX : The x-axis scaling factor. Must be an integer > 0. Default is 2.

• scaleY : The y-axis scaling factor. Must be an integer > 0. Default is scaleX.

• scale : Sets both the x-axis and y-axis scaling factors. Must be an integer > 0.

• rotate : Allows rotating the image to one of the four orthogonal orientations. A string value. Must be one of:

  • "N" : Normal (not rotated). The default.
  • "R" : Clockwise (right) 90 degree rotation.
  • "L" : Counter-clockwise (left) 90 degree rotation.
  • "I" : Inverted 180 degree rotation.

• paddingwidth : Sets the left and right padding (in points/pixels) around the rendered barcode. Rotates and scales with the image.

• paddingheight : Sets the top and bottom padding (in points/pixels) around the rendered barcode. Rotates and scales with the image.

• monochrome : Sets the human-readable text to render in monochrome. Boolean true or false. Default is false which renders 256-level gray-scale anti-aliased text.

All other options are BWIPP specific. You will need to consult the BWIPP documentation to determine what options are available for each barcode type.

Note that bwip-js normalizes the BWIPP width and height options to always be in millimeters. The resulting images are rendered at 72 dpi. To convert to pixels, use a factor of 2.835 px/mm (72 dpi / 25.4 mm/in). The bwip-js option scale multiplies both the width and height options. Likewise, the discrete scaling factors scaleX and scaleY multiply the width and height options, respectively.

Command Line Interface

bwip-js can be used as a command line tool.

npm install -g bwip-js
bwip-js --help

Usage example:

bwip-js --bcid=qrcode --text=123456789 ~/qrcode.png

Installation

You can download the latest npm module using:

npm install bwip-js

Or the latest code from github:

https://github.com/metafloor/bwip-js

(The bwip-js master branch and the npm version are kept sync'd.)

The software is organized as follows:

bwip-js/
    barcode.ps       # The BWIPP PostScript barcode library
    bwipjs.js        # Main bwipjs code
    bwipp.js         # The cross-compiled BWIPP code
    demo.html        # The bwipjs demo
    freetype.js      # The Emscripten-compiled FreeType library
    node-bwipjs.js   # Node.js module
    node-zlibPNG.js  # Node.js module that implements a PNG encoder
    package.json     # Node.js/npm configuration
    server.js        # Node.js example server
    fonts/           # OCR and Inconsolata font files
    lib/             # Utilities required by the demo

The above files are part of the master branch. If you wish to compile bwip-js on your own, you will need to clone the develop branch, which contains the cross-compiler, test framework, code-coverage files, benchmark framework, image proofs, etc. Everything used to create and validate bwip-js.

For details on how to compile and test bwip-js, see Compiling bwipjs.

Demo Usage

To run the demo from your HTTP server, you should install the bwip-js directory under the server's root document directory and modify the server's configuration files, if necessary. Then navigate your browser to bwip-js/demo.html.

You cannot run the demo using a file:// URL. The freetype library demand loads files using XHR, which must run over HTTP.

If you would like to implement your own interface to bwip-js, see Integrating With Your Code. You should also look at the node-bwipjs.js module to see how it was done for Node.js.

Supported Barcode Types

• auspost : AusPost 4 State Customer Code • azteccode : Aztec Code • azteccodecompact : Compact Aztec Code • aztecrune : Aztec Runes • bc412 : BC412 • channelcode : Channel Code • codablockf : Codablock F • code11 : Code 11 • code128 : Code 128 • code16k : Code 16K • code2of5 : Code 25 • code32 : Italian Pharmacode • code39 : Code 39 • code39ext : Code 39 Extended • code49 : Code 49 • code93 : Code 93 • code93ext : Code 93 Extended • codeone : Code One • coop2of5 : COOP 2 of 5 • daft : Custom 4 state symbology • databarexpanded : GS1 DataBar Expanded • databarexpandedcomposite : GS1 DataBar Expanded Composite • databarexpandedstacked : GS1 DataBar Expanded Stacked • databarexpandedstackedcomposite : GS1 DataBar Expanded Stacked Composite • databarlimited : GS1 DataBar Limited • databarlimitedcomposite : GS1 DataBar Limited Composite • databaromni : GS1 DataBar Omnidirectional • databaromnicomposite : GS1 DataBar Omnidirectional Composite • databarstacked : GS1 DataBar Stacked • databarstackedcomposite : GS1 DataBar Stacked Composite • databarstackedomni : GS1 DataBar Stacked Omnidirectional • databarstackedomnicomposite : GS1 DataBar Stacked Omnidirectional Composite • databartruncated : GS1 DataBar Truncated • databartruncatedcomposite : GS1 DataBar Truncated Composite • datalogic2of5 : Datalogic 2 of 5 • datamatrix : Data Matrix • datamatrixrectangular : Data Matrix Rectangular • ean13 : EAN-13 • ean13composite : EAN-13 Composite • ean14 : GS1-14 • ean2 : EAN-2 (2 digit addon) • ean5 : EAN-5 (5 digit addon) • ean8 : EAN-8 • ean8composite : EAN-8 Composite • flattermarken : Flattermarken • gs1-128 : GS1-128 • gs1-128composite : GS1-128 Composite • gs1-cc : GS1 Composite 2D Component • gs1datamatrix : GS1 Data Matrix • gs1datamatrixrectangular : GS1 Data Matrix Rectangular • gs1northamericancoupon : GS1 North American Coupon • gs1qrcode : GS1 QR Code • hanxin : Han Xin Code • hibcazteccode : HIBC Aztec Code • hibccodablockf : HIBC Codablock F • hibccode128 : HIBC Code 128 • hibccode39 : HIBC Code 39 • hibcdatamatrix : HIBC Data Matrix • hibcdatamatrixrectangular : HIBC Data Matrix Rectangular • hibcmicropdf417 : HIBC MicroPDF417 • hibcpdf417 : HIBC PDF417 • hibcqrcode : HIBC QR Code • iata2of5 : IATA 2 of 5 • identcode : Deutsche Post Identcode • industrial2of5 : Industrial 2 of 5 • interleaved2of5 : Interleaved 2 of 5 (ITF) • isbn : ISBN • ismn : ISMN • issn : ISSN • itf14 : ITF-14 • japanpost : Japan Post 4 State Customer Code • kix : Royal Dutch TPG Post KIX • leitcode : Deutsche Post Leitcode • matrix2of5 : Matrix 2 of 5 • maxicode : MaxiCode • micropdf417 : MicroPDF417 • microqrcode : Micro QR Code • msi : MSI Modified Plessey • onecode : USPS Intelligent Mail • pdf417 : PDF417 • pdf417compact : Compact PDF417 • pharmacode : Pharmaceutical Binary Code • pharmacode2 : Two-track Pharmacode • planet : USPS PLANET • plessey : Plessey UK • posicode : PosiCode • postnet : USPS POSTNET • pzn : Pharmazentralnummer (PZN) • qrcode : QR Code • rationalizedCodabar : Codabar • raw : Custom 1D symbology • royalmail : Royal Mail 4 State Customer Code • sscc18 : SSCC-18 • symbol : Miscellaneous symbols • telepen : Telepen • telepennumeric : Telepen Numeric • upca : UPC-A • upcacomposite : UPC-A Composite • upce : UPC-E • upcecomposite : UPC-E Composite •\n