4.8 KiB
Transpilation
CoffeeScript 2 generates JavaScript that uses the latest, modern syntax. Your runtime might not support all of that syntax. If so, you need to transpile the JavaScript. To make things a little easier, CoffeeScript has built-in support for the popular Babel transpiler.
Quickstart
From the root of your project:
npm install --save-dev babel-core babel-preset-env
echo '{ "presets": ["env"] }' > .babelrc
coffee --compile --transpile --inline-map some-file.coffee
About Transpilation
Transpilation is the conversion of source code into equivalent but different source code. In our case, we want to convert modern JavaScript into older JavaScript that will run in older versions of Node or older browsers; for example, { a } = obj into a = obj.a. This is done via transpilers like Babel, Bublé or Traceur Compiler.
CoffeeScript includes a --transpile option when used via the coffee command, or a transpile option when used via Node. To use either, Babel must be installed in your project:
npm install --save-dev babel-core
By default, Babel doesn’t do anything—it doesn’t make assumptions about what you want to transpile to. You might know that your code will run in Node 8, and so you want Babel to transpile modules and JSX and nothing else. Or you might want to support Internet Explorer 8, in which case Babel will transpile every feature introduced in ES2015 and later specs.
If you’re not sure what you need, a good starting point is babel-preset-env:
npm install --save-dev babel-preset-env
See Babel’s website to learn about presets and plugins and the multitude of options you have.
Simply installing babel-preset-env isn’t enough. You also need to define the configuration options that you want Babel to use. You can do this by creating a .babelrc file in the folder containing the files you’re compiling, or in any parent folder up the path above those files. So if your project is in ~/app and your files are in ~/app/src, you can put .babelrc in either ~/app or in ~/app/src. You can also define the Babel options via a babel key in the package.json file for your project. A minimal .babelrc file (or package.json babel key) for use with babel-preset-env would be just { "presets": ["env"] }.
Once you have babel-core and babel-preset-env (or other presets or plugins) installed, and a .babelrc file (or package.json babel key) in place, you can use coffee --transpile to pipe CoffeeScript’s output through Babel using the options you’ve saved.
If you’re using CoffeeScript via the Node API, where you call CoffeeScript.compile with a string to be compiled and an options object, the transpile key of the options object should be the Babel options:
CoffeeScript.compile(code, {transpile: {presets: ['env']}})
You can also transpile CoffeeScript’s output without using the transpile option, for example as part of a build chain. This lets you use transpilers other than Babel, and it gives you greater control over the process. There are many great task runners for setting up JavaScript build chains, such as Gulp, Webpack, Grunt and Broccoli.
Note that babel-preset-env doesn’t automatically supply polyfills for your code. CoffeeScript itself will output Array.indexOf if you use the in operator, or destructuring or spread/rest syntax; and Function.bind if you use a bound (=>) method in a class. Both are supported in Internet Explorer 9+ and all more recent browsers, but you will need to supply polyfills if you need to support Internet Explorer 8 or below and are using features that would cause these methods to be output. You’ll also need to supply polyfills if your own code uses these methods or another method added in recent versions of JavaScript. One polyfill option is babel-polyfill, though there are many other strategies.