coffee-inline-map/README.html

Compile CoffeeScript files with inline source maps

<h1 id="coffee-inline-map">coffee-inline-map</h1>
<p>Compile CoffeeScript files with inline source maps.</p>
<h2 id="features">Features</h2>
<ul>
<li>Error reporting similar to the original CoffeeScript compiler.</li>
<li><code>.litcoffee</code> support.</li>
</ul>
<h2 id="example">Example</h2>
<pre><code>$ cat a.coffee
module.exports = (something) -&gt; console.log something

$ coffee-inline-map a.coffee | fold -w72
// Generated by CoffeeScript 1.6.3
(function() {
  module.exports = function(something) {
    return console.log(something);
  };

}).call(this);

//@ sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaW
xlIjoiYS5jb2ZmZWUiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyJhLmNvZmZlZSJdLC
JuYW1lcyI6W10sIm1hcHBpbmdzIjoiO0FBQUE7Q0FBQSxDQUFBLENBQWlCLEdBQVgsQ0FBTi
xFQUFrQjtDQUFzQixFQUFSLElBQU8sRUFBUCxFQUFBO0NBQWhDLEVBQWlCO0NBQWpCIiwic2
91cmNlc0NvbnRlbnQiOlsibW9kdWxlLmV4cG9ydHMgPSAoc29tZXRoaW5nKSAtPiBjb25zb2
xlLmxvZyBzb21ldGhpbmdcbiJdfQ==

$ coffee-inline-map -h
Usage: coffee-inline-map [options] [file.coffee]

Available options:
  -h, --help            output usage information &amp; exit
  -V, --version         output the version number &amp; exit
  -o, --output [FILE]   write result to a FILE instead of stdout
  -l, --literate        treat stdin as literate style coffee-script
  -b, --bare            compile without a top-level function wrapper
      --no-map          don&#39;t include inline source map (why?)
</code></pre>
<h2 id="installation">Installation</h2>
<pre><code># npm install -g coffee-inline-map</code></pre>
<h2 id="compilation">Compilation</h2>
<pre><code>$ make compile</code></pre>
<h2 id="browserify-make-commonjs-depend">browserify &amp; make-commonjs-depend</h2>
<p>To verify the text below you'll need to clone this repo, run 'make compile', install <a href="https://github.com/gromnitsky/make-commonjs-depend">make-commonjs-depend</a> &amp; browserify.</p>
<p>Look into repo's <code>test/data</code> directory. Ignore <code>*.should</code> files. I'll wait.</p>
<p>Then</p>
<pre><code>$ cd src
$ ls *coffee
a.coffee
b.litcoffee
main.coffee
</code></pre>
<p>Here <code>main.coffee</code> depends on <code>a.coffee</code> &amp; <code>b.litcoffee</code>. For out site we need just 1 <code>public/bundle.js</code> file which will include the result form the compilations of our all CoffeeScript files.</p>
<p>We want to rebuild <code>public/bundle.js</code> only &amp; only on .coffee files change. That's obviously a job for make.</p>
<pre><code>$ cat Makefile
COFFEE_COMPILER := ../../../bin/coffee-inline-map

out := ../public
js_temp := \
    $(patsubst %.coffee,%.js,$(wildcard *.coffee)) \
    $(patsubst %.litcoffee,%.js,$(wildcard *.litcoffee))
bundle := $(out)/bundle.js

.PHONY: depend compile compile-js clean

all: compile

%.js: %.coffee
    $(COFFEE_COMPILER) $&lt; -o $@

%.js: %.litcoffee
    $(COFFEE_COMPILER) $&lt; -o $@

depend: compile-js
    make-commonjs-depend *js -o js.mk

-include js.mk

compile-js: $(js_temp)
compile: compile-js $(bundle)

$(bundle): main.js
    @mkdir -p $(out)
    browserify -d $&lt; -o $@

clean:
    rm -f js.mk $(js_temp) $(bundle)
</code></pre>
<p>To create a dependency tree, we run</p>
<pre><code>$ make depend
../../../bin/coffee-inline-map a.coffee -o a.js
../../../bin/coffee-inline-map main.coffee -o main.js
../../../bin/coffee-inline-map b.litcoffee -o b.js
make-commonjs-depend *js -o js.mk
</code></pre>
<pre><code>$ cat js.mk
a.js:
b.js:
main.js: \
  a.js \
  b.js
</code></pre>
<p>It's unfortunate that make-commonjs-depend supports only javascript. That's why before running it, make needs to compile all coffescript files.</p>
<p>Then compile the bundle</p>
<pre><code>$ make compile
../../../bin/coffee-inline-map main.coffee -o main.js
browserify -d main.js -o ../public/bundle.js
</code></pre>
<p>As a little homework, try to guess why <code>main.js</code> was recompiled here, when at first glance it should rather not.</p>
<p>Run again</p>
<pre><code>$ make compile
make[1]: Nothing to be done for `compile&#39;.
</code></pre>
<p>Notice that the nothing was recompiled for the 2nd time. That's our goal!</p>
<pre><code>$ touch a.coffee
$ make compile
../../../bin/coffee-inline-map a.coffee -o a.js
../../../bin/coffee-inline-map main.coffee -o main.js
browserify -d main.js -o ../public/bundle.js
</code></pre>
<p>Yay! Then open <code>public/index.html</code> in Chrome and switch to the console view. (Make sure to turn on 'Enable source maps' in Developer Tool's settings.)</p>
<h2 id="jeez-mate-why-are-you-doing-this-rigmarole">Jeez mate, why are you doing this rigmarole?</h2>
<p>Every dependency &amp; every file should be compiled/processed only once.</p>
<p>This seems meaningless for a bunch of small .coffee files but becomes very useful for large projects with several complex browserify output targets.</p>
<h2 id="why-not-just-use-coffeeify-plugin-for-browserify">Why not just use coffeeify plugin for browserify?</h2>
<ol style="list-style-type: decimal">
<li>browserify can't (&amp; shouldn't) check what has changed in our source files to decide whether it's time to recompile.</li>
<li>Error reporting.</li>
</ol>
<h2 id="why-are-you-using-outdated-make-instead-of-cake-jake-or-grunt-its-not-1977-anymore">Why are you using outdated make instead of cake, jake or grunt? It's not 1977 anymore!</h2>
<p>facepalm.jpg</p>
<p>Dude. <br/> Just take a walk for 10 minutes &amp; no one will hurt.</p>
<h2 id="bugs">BUGS</h2>
<ul>
<li>Reading from stdin doesn't work in Windows.</li>
</ul>
<h2 id="news">NEWS</h2>
<h3 id="section">0.3.0</h3>
<ul>
<li><code>-b</code> CLO.</li>
<li>Include 'generated by ...' header.</li>
</ul>
<h3 id="section-1">0.2.0</h3>
<ul>
<li>Update for CoffeeScript 1.6.3.</li>
<li>Recognize <code>.coffee.md</code> extension.</li>
<li><code>-l</code> CLO.</li>
</ul>
<h3 id="section-2">0.1.0</h3>
<ul>
<li>Add reading from stdin.</li>
<li>Fix an unheplful crash for EPIPE error.</li>
</ul>
<h2 id="license">License</h2>
<p>MIT.</p>