boiledjs

Engine agnostic JavaScript compiler.

npm install boiledjs
10 downloads in the last week
20 downloads in the last month

BoiledJS

JavaScript source compiler. Uses comment annotation to indicate requirements, inlines, exports, etc.

Idea

Enable multi-file source code annotated for compilation into a single module/app file. All necessary information for compilation is contained within the source files being compiled.

The compilation is modular overall in that required files will be isolated in their own closures. An API can be exposed in two ways: by modifying the global namespace, or by using the /// exports annotation.

The name BoiledJS refers to this being a compiler which cooks (or boils, hehe) your source code into something that's easily consumable. That consumable is specifically a single javascript file. It also refers to the core goal which is boilerplate reuse via compile time dependency injection.

Usage

boiledjs [--verbose] [--target=name] jsfile
boiledjs --help

Source Annotation

All annotation comments start with triple forward slashes followed by a keyword: require, read, export, target, or namespace

Require a source file

There two valid require forms.

Require after a variable declaration.

The require will be assigned to the variable that is declared on the same line. The variable declaration must be singular and on its own line or the annotation will be ignored.

var variable; /// require "filename"

Require without a variable declaration.

This will not make any local variable declarations. If the optional variable name is present, then the exports will be assigned blindly. If the variable does not already exist, the global namespace will be modified.

Note: If you are using a dot separated variable name, only the last part will be created if it does not exist.

/// require "filename" [as "variable"]

Read a file.

This is similar to requiring a file except that the contents of the file will be stored as text rather than interpreted as a script.

Like require, there are two valid forms.

Read after a variable declaration.

The text will be assigned to the variable declared on the same line. The variable declaration must be singular and on its own line or the annotation will be ignored.

var variable; /// read "filename"

Read without a variable declaration.

This will not make any local variable declarations. Unlike require, the variable name parameter is required. If the variable does not already exist, the global namespace will be modified.

Note: If you are using a dot separated variable name, only the last part will be created if it does not exist.

/// read "filename" into "variable"

Export a variable

Like CommonJS modules, there is an implicitly created "exports" object for each required file. To expose an API, you add properties to it, or replace it completely using this annotation.

The variable name should refer to an already declared variable.

The optional property name indicates that the variable should be attached to the existing exports object as a named property. Without a property name, the variable's value will replace the exports object completely.

/// export "variable" [as "property"]

Set source section build target

When this annotation is found, all source code following it up to the next target annotation or the end of the file, will only be included for the specific build targets.

/// target ["target1", "target2", ...]

To go back to including source in all targets, just add a target line with no target list.

/// target

Target "none" is a special target that can never actually be used. As such, any code targetted at "none" will always be removed from the compiled source.

/// target none

Create a namespace

Assign a new object to a variable if the variable is not already an object. This does not make any local variable declarations. If the variable does not already exist, the global namespace will be modified.

Note: If you are using a dot separated variable name, only the last part will be created if it does not exist.

/// namespace "path.to.variable"

This is identical to the following code.

if (typeof path.to.variable === "undefined" || !(path.to.variable instanceof Object)) path.to.variable = {};

To be completely safe you would need to write the following.

/// namespace "path"
/// namespace "path.to"
/// namespace "path.to.variable"
npm loves you