LiveScript transform for Browserify
Lsify lets you write LiveScript and have Browserify automatically compile it into JavaScript. This means that JavaScript and LiveScript can be mixed in the same project arbitrarily; lsify will cause Browserify to compile the LiveScript, which will then be bundled as JavaScript along with any other JavaScript files needed for the bundle.
For this to work properly, LiveScript files must have an extension of ".ls" (which they do anyway for LiveScript to compile them) and must be required with this extension:
test = require('./test.ls');
Options can be passed through to the LiveScript compiler either through the API:
bundle.transform(require("lsify"), { header: false, const: true });
or through package.json:
{
"name": "my-project",
"browserify": {
"transform": [
["lsify", { "header": false, "const": true }]
]
}
}
For the most part, options are simply passed along to the LiveScript compiler. If further options are added in the future (and if they don't cause breaking changes like source maps did), lsify should simply support them because of this. However, since the environment in a Browserify setup is a little different than in normal LiveScript compilation, there are a pair of exceptions.
The first is the bare
option, which in the LiveScript compiler defaults to false
. Browserify bundles a lot of files
together and adds some infrastructure around them, meaning that the immediately-invoked functions in a non-bare
compiled file can cause problems. Therefore, in lsify, the default value of bare
is true
.
The second differnce is in...
LiveScript added source maps in 1.4.0, though they did it in a slightly unexpected way which makes the
compiler output its code differently when creating source maps as opposed to not creating them. Therefore, just passing
the map
option as-is broke compilation in 0.2.0.
Support has been added in 0.3.0 to allow source maps to be properly created (or not). However, only embedded source
maps make any sense in a Browserify context. Therefore, the only values from the LiveScript compiler's map
option
that are supported are "none"
and "embedded"
. Alternately, you can use true
or false
to indicate whether you
want source maps generated and embedded.
In the LiveScript compiler, the default is "none"
, meaning that no source maps are generated. However, in Browserify,
a specific option (debug
) is set to indicate that source maps are wanted. If this option is not set, the bundling
process eliminates comments (and therefore any already-embedded source maps) anyway. So rather than having to set two
options (one on Browserify and one on lsify) to do source mapping, lsify defaults map
to true
. Therefore
turning on Browserify's debug
will by default generate LiveScript source maps, while turning debug
off will make
those source maps be ignored. Which is probably how we want it.
Embeddeding source maps allows JavaScript debugging tools (including the Chrome debugger and Firebug) to display the original LiveScript code and to translate locations, breakpoints, etc. back to the original source. Essentially it lets you debug original LiveScript instead of compiled, bundled JavaScript.
As noted above, source maps require that the Browserify debug
option be set to true
. Otherwise lsify will still
generate the source maps, but Browserify will drop them when it does its bundling.
0.3.1
- Changed the default on the
map
option totrue
.
0.3.0
- Added embedded source map support.
0.2.0
- Fixed LiveScript require to use all lower-case. This was needed because LiveScript 1.4.0 changed its package name to be all lower-case. While this is probably the way it should be, it does mean that lsify now requires LiveScript 1.4.0+.
- Removed peer dependencies. The changes recently made in Node itself make them unnecessary.
- Updated CI config to test against Node up to version 4.1.