Writing Node.js modules in ClojureScript

2012-06-04T00:00:00+00:00

At SourceNinja we recently expanded our offering to track Node.js, and as part of that we released a Node.js module. I love Clojure, and used this opportunity to finally take a look at ClojureScript, and specifically using Node.js as a deploy target.

There is some documenation for running ClojureScript on top of Node.js, but so far no documentation for deploying a module written in ClojureScript to npm. Think of this post as a report describing what worked, what didn’t and where we found gaps. I’m going to assume you know Clojure, and that you have installed Node.js. If you haven’t installed Node.js yet I highly recommend you use nvm, it’s the bee’s knees.

Getting Started

Let’s get started. Create a new project directory. You’re going to need two sub-folders, one named src, and another named lib. src is for your raw ClojureScript, the lib direcory will contain the code generated by the ClojureScript compiler.

Start out with a simple ClojureScript program

As stated in other guides, in order to make this program run with Node.js you need to specify a main by setting the value of *main-cli-fn* to some function.

To compile the ClojureScript we use the incantation below. cljsc will take all *.cljs files found in the src directory, compile them to js and spit the result out via stdout. We pipe the output to a js file matching the module name in the lib directory. The fact that we use the lib directory is important, because that’s where Node.js is going to look for code.

The only option which is stricly neccessary is :target which should be set to :nodejs. This option generates a main functions which in turn calls the function specified by *main-cli-fn*. While the other are not required they will make this whole process go much smoother. We found that setting the optimizations level to anything other than :simple produced unreliable code which was difficult to debug. For our purposes heavy optimization wasn’t neccessary so I didn’t invest much effort in getting it to work, give it a shot, your millage may vary.

Most of your debugging time is going to be tracing through the generated JS code, for this reason we always enable :pretty-print which results in human-readable code being generated.

Export Functions

At this point we have a fully functional Node.js program. When we run the generated code we should see the following.

Great it works, but every time your module is included it’s going to run whatever function is bound to *main-cli-fn*. Leaving it unbound isn’t an option so we need to bind it to a noop function. The final form is below.

To turn this program into a module we need a couple small additions. The first is that we need to export/extern the public functions so that they are visible to node. We do this by adding a file lib/main.js.

You need to import the generated javascript code outputed by the ClojureScript compiler, this is done by the require("./sample.js"). The actual export is done by the next line exports.core = sample.sample.core, this makes the sample.core namespace defined by our ClojureScript program visible to node.js. All functions declared by your clojure namespace should now be accessible.

Publishing the Module

The last addition is the packages.json file which lives at your project root. You can find lots of documentation for this file, so I won’t spends lots of time on it, I’ll just emphasise a couple points.

Spend some time verifying which version of Node.js introduced the functionality you require. For instance we use npm programatily, but the functionality wasn’t introduced until 6.0 which is newer than the verion deployed by Heroku. Node.js is very young, and is a bit of a moving target, spending a little time up front will prevent you from being burned. Using nvm becomes invaluable when attempting to validate your module against different versions of node. Oh, and please populate the repository and license fields, it’s just part of being a good open source citizen.

At this point from your project root you can execute npm publish and npm will walk you through creating an account and publish your module to npm.

Pro Tips

When passing data from ClojureScript to Node.js your going to need to convert it from a ClojureScript data st ructure to a javascript object. There have been various examples published of how to do this on the interwebs, but all were buggy. We settled on the following, which worked for us, but it is admittedly limited.

Testing

Unit testing can be done using the built-in clojure.test API, and that seems to be the recommended method. It should be possible to test functionality via one of the Node.js frameworks such as vows, but that’s another blog post. If you want to test the integration between other Node.js programs and your newly minted module you can create a test program which requires your module and then copy your module to the node_modules sub-directory which allows you to do pre-publish testing. This is what we do as part of our last round of testing before we publish.

Don't Start a Company

2010-10-11T00:00:00+00:00

I can’t start that new company. I don’t know how to do sales. I don’t know how to dev. I don’t understand business. I don’t understand financing. I don’t have enough money saved. The economy isn’t doing well. I don’t have enough time to work on my idea. Family life is too hectic. I’m the sole breadwinner. I’ve got young kids at home. Things are really interesting at work. I want to finish this one project. A bunch of people left and the team depends on me. A raise is right around the corner. Things are getting better. There is too much uncertainty. I’m scared.

It’s Never A Good Time

I’m not dismissing your reasons for not starting a company. You may have very valid reasons for not wanting to jump ship. Who am I to judge? The truth is, it’s never a good time to start a company. Life is never going to offer up that opportune time where all the planets align and all obstacles melt before you. Being successful is about making the best out of the hand you’re given. It’s about being determined/persistant/foolhardy enough to push through adversity and do what’s difficult.

Two days after I quit my cushy corporate job my wife gave birth to our first son. Yeah, it’s been less than ideal and at times, it sucks. No matter what you do you are either neglecting your family or your business. My cofounder is the breadwinner for his family of three, and I guarantee that fact weighs on his conscious all the time. Both of us had jobs which paid us well, had coworkers we liked, and we were respected. I’m not telling you these things to show you how awesome we are, I’m telling you so that you know you’re not alone.

Don’t Wait

If you’re waiting for someone to tell you it’s going to be ok, and everything will work out, that person isn’t coming. You’re going to have to take that leap on your own. Be under no illusions, starting a company is hard. It’s the hardest thing I’ve done. In fact, it is the hardest thing I’ve done other than be a parent. But, if you have the stamina, the determination, and the will, do it.

What’s the worst that can happen?

If you fail, you haven’t. You have attempted something that few are willing to try. You can always get a corporate job and you will never say to yourself, “what if?”

A Unique Blog Title