node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


Preprocessor.js - A JavaScript preprocessor

Provides a JavaScript source file preprocessor, e.g. to build different versions of a library. It's for example used to build ProtoBuf.js (its build and main script are quite good examples).


  • Includes (always relative to the baseDirectory, defaults to "."):
// #include "path/to/file.js" 
  • Static conditions:
// #ifdef FULL 
console.log("Including extension");
// #include "path/to/extension.js" 
// #else 
console.log("Not including extension");
// #endif 
  • Inverse static conditions:
// #ifndef FULL 
console.log("Not including extension");
// #else 
console.log("Including extension");
// #include "path/to/extension.js" 
// #endif 
  • Evaluable conditions:
// #if 1==2 
// #elif 2==2 
// #endif 
  • Inline variables and functions:
// #define var PI=Math.PI 
// #define function RADTODEG(x){return x*180/PI} 
var angle = // #put RADTODEG(3)+";" 
  • Writing the result of evaluated expressions:

    var version = // #put '"'+VERSION+'";"' 
    var str = // #put "\"Hello world!\";" 
    var onePlusOne = // #put (1+1)+";" 


  • CommonJS compatible
  • RequireJS/AMD compatible
  • Shim compatible (include the script, then use var ByteBuffer = dcodeIO.ByteBuffer;)
  • node.js compatible, also available via npm
  • Closure Compiler ADVANCED_OPTIMIZATIONS compatible (fully annotated, Preprocessor.min.js has been compiled this way, is the source map)
  • Fully documented using jsdoc3
  • Well tested through nodeunit
  • Zero production dependencies
  • Small footprint

Command line utility

Install via npm: npm -g install preprocessor

Command line

Usage: preprocess sourceFile [baseDirectory] [-myKey[=myValue], ...] [> outFile]

preprocess Source.js . -FULL=true > Source.full.js


The API is quite simple:

var result = new Preprocessor(

with baseDirectoryOrIncludes being either a string containing the path to the base directory or an object of included sources by filename. When running in a browser, only the later is supported.

node.js / CommonJS

var Preprocessor = require("preprocessor");
var source = "..."; // e.g. through fs.readFile 
var pp = new Preprocessor(source, ".");
    FULL: true

RequireJS / AMD

require(["/path/to/Preprocessor.js"], function(Preprocessor) {
    var source = "..."; // e.g. through fs.readFile / $.ajax 
    var pp = new Preprocessor(source, ".");
        FULL: true

Browser / shim

Note: To use the #include directive in the browser, do not specify the base directory but an object of included sources by filename:

<script src="//"></script>
var Preprocessor = dcodeIO.Preprocessor;
var source = "..."; // e.g. through. $.ajax 
var pp = new Preprocessor(source, {
    "./includes/extension.js": "var myVar = 2;" // <- #include "includes/extension.js" 
    FULL: true

Using includes instead of a base directory like shown in the example above is supported regardless of the platform you are on.



Tests (& Examples) Build Status


Apache License, Version 2.0 -