How To Migrate a Project From Javascript to Coffeescript

It was surprisingly hard to find articles on how to convert entire projects from JavaScript to Coffeescript. Perhaps few people need convert an existing project: they either start with Coffeescript or deliberately chose to use JavaScript (or the conversion is super obvious to everyone else).

I, of course, am addicted to the sweet sweet syntactic sugar of Coffeescript and have never converted a project, until now.

Here are my steps:

Install Node

Actually, the first step is to install node, since Coffeescript is a npm package. The official node website has many downloadable binaries.

Install Coffeescript

$ npm install -g coffee-script

Get ready for the syntactic sugar rush!

Install js2coffee

js2coffee is a package that converts JavaScript to Coffeescript. It’s very nice for converting individual files or small snippets of code, but it’s not project aware. When your project is spread over several files, you need to do some manual touchups.

$ npm install -g js2coffee

Convert all the Javascript

Now it’s time to convert. Temporary move all your minified JavaScript libraries like jquery.min.js (and any other JavaScript you don’t want converted) to a new directory.

Suppose my directory structure looks like:

 
project/
**js/
****libs/
******jquery.min.js
****my_code/
******my_code.js

After moving all of the files I don’t want converted, it’ll look like:

project/
**js/
****my_code/
******my_code.js
**libs/
****jquery.min.js

In the js directory, Use a nice bash script to invoke js2coffee on every JavaScript file (from StackOverflow).

Or a nice one-liner:

$ find . -type f -name '*.js' | while read f; do echo "grinding $f to ${f/.js/.coffee} "; js2coffee "$f" > "${f/.js/.coffee}"; done

 
project/
**js/
****my_code/
******my_code.js
******my_code.coffee
**libs/
****jquery.min.js

Now rename your js directory to Coffeescript and delete all the *.js files.

$ rm $(find . -type f -name '*.js' )

 
project/
**src/
****my_code/
******my_code.coffee
**libs/
****jquery.min.js

Create a new directory for your final compiled JavaScript and move your unconverted JavaScript there.

 
project/
**js/
****libs/
******jquery.min.js
**src/
****my_code/
******my_code.coffee

Now you can use coffee-script to generate the JavaScript.

$ coffee --compile --output js/ src/

 
project/
**js/
****libs/
******jquery.min.js
****my_code/
******my_code.js
**src/
****my_code/
******my_code.coffee

Manual Edits

Since Coffeescript will wrap everything to prevent them from leaking into the global namespace, you will need to do some futzing to get everything connected correctly.

Here’s a great answer from StackOverflow on attaching variables to the global object.

j2coffee is also not smart enough to recognize frameworks like Backbone, so you’ll probably have to edit something like:

Candy = Backbone.Model.extend(.....

to

class Candy extends Backbone.Model

The futzing shouldn’t be too bad for a newer project, but I can see it being terribly for something more legacy. The sooner the conversion the easier the conversion, if you want to convert at all.

Coffeescript is a lot easier to read and maintain than plain olde JavaScript. For me, the cost of conversion is definitely worth it. Hope this helps you, and let me know of snazzier tools, in case I have to do this in the future.