Setting Up A Node.cljs Project With Leiningen and NPM

Before we begin, make sure you can start a node.cljs repl first

One important thing I want to highlight is that you should have a stable version of node 0.12.X as the linked wiki page says. Additionally, you want to make sure you have npm installed so you can install node packages later on. Finally, I’m also assuming that you already have Clojure and Clojurescript setup with Leiningen.

Let’s begin.

Start by making a new leiningen project. 

lein new node_project

And then move into that directory.

Start by editing your project.clj file to look something like this:

(defproject node_test "0.1.0-SNAPSHOT"
  :dependencies [[org.clojure/clojure "1.7.0-RC1"]
                 [org.clojure/clojurescript "0.0-3269"]
                 [org.clojure/core.async "0.1.346.0-17112a-alpha"]]
  :profiles {:dev
             {:dependencies [[com.cemerick/piggieback "0.2.1"]
                             [org.clojure/tools.nrepl "0.2.10"]]
              :plugins [[lein-cljsbuild "1.0.5"]]
              :source-paths ["src" "dev"]
              :repl-options {:nrepl-middleware [cemerick.piggieback/wrap-cljs-repl]}}}
  :clean-targets
  [[:cljsbuild :builds 0 :compiler :output-to]
   :target-path
   :compile-path]
  :cljsbuild {:builds
              [{:id "dev"
                :source-paths ["src"]
                :compiler {:output-dir "out"
                           :output-to "index.js"
                           :optimizations :none
                           :source-map "src-maps"
                           :target :nodejs}}]})

It’s very important that you use versions of Clojure and Clojurescript greater than or equal to the ones I’ve listed. I’ve ran into a lot of issues trying a setup like this before finding one that worked. It was mostly due to old versions of piggieback and Clojurescript.

I added the piggieback related dependencies in dev for the node.js REPL we’re going to be using later. The clean-targets are for the command 

lein clean

Because cljsbuild deprecated its clean function.

A few more things to note:

We’re using no optimizations and targeting node.js. Having optimizations set to :simple, I ran into issues with core.async macros. 

Next, we need to setup the node side of the project. Inside the same project folder, run:

npm init

You can pretty much press enter for every single prompt, except the entry point one. There you want it to be named app.js, not index.js as we specified in the project.clj. We can’t run index.js directly due to optimizations being set to none, so cljsbuild will output multiple files.

Next, you can install a web framework using npm like express:

npm install --save express

Now that we have Express.js installed, we can just make a simple hello world web application in clojurescript.

Rename src/node_test/core.clj to src/node_test/core.cljs.

Then in the file put this:

(ns node-test.core
  (:require [cljs.nodejs :as node]))

(def express (node/require "express"))

(def app (new express))

(defn -main
  []
  (.listen app
           3000
           (fn []
             (js/console.log "App Started at http://localhost:3000"))))

(set! *main-cli-fn* -main)

Then you want to compile your clojurescript to javascript with:

lein cljsbuild auto

Now that we have our index.js file, we need to make the file for node to run the application.

Make a file called app.js in the root of your project folder with this as its contents:

// Bootstrap node.js
require('./out/goog/bootstrap/nodejs');

// Our app compiled by cljsbuild
require('./index.js');

// The core of our code
require('./out/node_test/core');

// The core of cljs
require('./out/cljs/core');

// Run main
// NOTE: Dashes in namespaces are replaced by underscores.
node_test.core._main();

If you’ve changed anything, replace the paths with the correct one.

Now, you can start the app with node.js:

$ node app.js
App Started at http://localhost:3000

And if you visit that url, you’ll receive an error message about not being able to GET /. That’s fine, we didn’t specify any routes.

If you liked this post and want to learn more about Node.cljs, sign up for my mailing list to get my latest posts in your inbox. Next post will be on how to develop this project shell further by adding in a cljs repl.

I’m also available for hire as a Clojure freelancer.

Becoming A Finisher

I’ve always known that I’m a starter and not much of a finisher. I’ll start a project and quickly get excited about a new idea and switch to the next shiny thing.

But I didn’t realize the extent of my problem until I had a conversation with some of my friends while playing Dota. My friends were talking about video games that they’ve completed, and that made me realize. I can’t even finish video games.

The games I’ve played are all competitive, like Dota or Hearthstone. No story to them. But even the competitive games with stories, like Starcraft 2, I can’t finish. Even single player games I can’t get halfway through. 

I started doing research on the subject by searching Hacker News, as it seems like a common problem and found a thread where Paul Graham gives some advice:

Taking on projects that are too big creates a situation like an airplane stalling because the angle of attack is too steep. Better only to take on projects so small that you know you can finish them, however humiliatingly small that may be initially. Then, with always finishing as a given, start to gradually crank up the ambition. But never so sharply that you stall.

Paul Graham

It may seem silly, but it looks like finishing is something you have to learn and practice. It’s a skill.

I’m going to take Paul Graham’s advice. 

Two things I’m going to start doing:

  • Using my Apple Watch as a pomodoro timer. Essentially the idea is you have periods of working and periods of relaxing. Usually it’s 25 minutes of work and 5 minutes of taking a break.
  • Breaking tasks up by single pomodoros to begin with. That’s humiliatingly small. 

Goal for tomorrow: Write the first post on Node.cljs in one pomodoro.

Stay tuned.

How To Refer To A Clojure Record In Another Namespace

I ran into an issue like usual. This time it seemed simple. I wanted to refer to a record that I def’d in another namespace.

The problem is, you can’t just do a :require and :refer it in regular Clojure. However, in Clojurescript this is how you would do it.

What you have to do is :import it. And the key trick to keep in mind when using :import on records and Clojure namespaces is that dashes are converted to underscores like packages in Java.

If you had a namespace like (ns foo-bar) in which there was a record called MyRecord, you would do something like this:

(:import [foo_bar MyRecord])

And you’ll be off to the races.

Node.cljs – The Secret Weapon Nobody Knows About

I came across a discussion on the Clojure mailing list.

Summary:

The original poster wants a web framework in Clojure. An actual framework, not a wimpy routing library like Compojure. Something closer to Rails or Django, where you don’t have to make your own framework every single time you start a project.

Of course, all the Clojure purists, hereby known as weenies, responded like so:

No Rage Face

Clojure weenies hate frameworks. They want composable libraries to make their own frameworks. Which sounds like a great idea! How could you argue against composable libraries? Composable! Modular! Sounds like a programmer’s wet dream. Libraries with single responsibilities that we can use anywhere!

The other people, hereby known as people that want to get shit done the other people, love Clojure. They want to use Clojure for everything. They bought into the claims that Clojure gives you a huge productivity boost. That functional programming is the future. But, the issue is they don’t see these benefits when doing web development. They’re used to being able to use Rails or Django to make CRUD applications in no time.


Two sides with reasonable arguments.

For the weenies, you can keep using pure Clojure.

For the other people, I have a solution that not many know about.

Node.cljs

As you might’ve guessed from the title, I think the middle ground and best of both worlds is Node.cljs. That’s node.js, but written with Clojurescript.

Why?

Clojurescript gives you Clojure that compiles to javascript. Which means you can get the entire Clojure language on the node platform. That includes macros, REPL based development, and all the libraries that support Clojurescript like Prismatic’s Schema or Core Async.

On the other end, node’s platform is amazing for web development. You can pick your favorite web framework, that’s right, framework. Like Express.js or Hapi.js. In case you cared about speed, node benchmarks a bit slower than Clojure.

Pros:

  • No JVM
  • Node platform -> web frameworks and libraries
  • Clojurescript libraries
  • Faster startup speed
  • No callback hell -> Use core.async for async operations.
  • Clojure features like integrated REPL, macros, etc.
  • Faster application development speed

Cons:

  • No JVM
  • Cljs tooling is still a little rough. You might run into some issues.
  • You have to know javascript.
  • A lot of code would be javascript interop.
  • A teeny bit complicated to setup a project.
  • Less functional code -> slightly more object oriented
  • Have to deal with clj->js and js->clj data structure conversions
  • Slower (according to Techempower’s benchmarks)

Interested in seeing how to get something like this setup? Stay tuned. Join my mailing list to get my posts automatically in your inbox.

Third Party Libraries In Clojurescript REPL

I ran into an issue at work earlier this week. I needed to include a phone number validation library in the Clojurescript side. It was libphonenumber by Google, which meant it was compiled with the Google closure library.

Great! That gets us halfway there.

That classifies it as a third party library, meaning in lein-cljsbuild you would specify it under the :libs key instead of the :preamble, :externs, or :foreign-libs.

I just want to make it clear that the :foreign-libs option is used for non Google closure code like jquery.

So if you’re using lein-cljsbuild, it’s just as easy as putting the directory path into :libs in a vector. But my problem was that I needed to access the third party library in my Clojurescript REPL while developing.

Under this documentation, it says:

Note: conveying the :libs option to the REPL so that it can find third-party JavaScript libraries has not yet been implemented.

I’ve found that to be untrue for the Rhino and Nashorn case, and I’m not completely sure if it’ll work in every single scenario yet so I’m hesitent to just change the wiki. I plan on doing some more investigation and then updating the wiki so other folks that come across this entry later won’t waste their time looking into the source code like I had to.

An example of how to use this with piggieback as the nrepl middleware:

(require 'cemerick.piggieback 'cljs.repl.rhino)
  (cemerick.piggieback/cljs-repl (cljs.repl.rhino/repl-env)
                                 :libs ["resources/js"])

Leiningen Profile Overrides

When developing applications in Clojure, one thing you might need is to be able to somehow keep different settings for each environment. For instance, you might want to be able to have different database settings for each environment.

This can be achieved with leiningen profiles:

:profiles {:dev-overrides {}
             :dev
             [:dev-overrides
              {:dependencies [[com.cemerick/austin "0.1.5"]
                              [com.cemerick/piggieback "0.1.4-SNAPSHOT"]
                              [ring-mock "0.1.5"]]
               :plugins [[com.keminglabs/cljx "0.5.0"]
                         [com.cemerick/austin "0.1.5"]
                         [lein-cljsbuild "1.0.3"]]}]
             :test-overrides {}
             :test
             [:dev
              :test-overrides]}

Assuming you have that :profiles sub-map somewhere in your project.clj map, it will override what’s in the root of the project map.

For instance:

(defproject ring_to_curl "0.1.0-SNAPSHOT"
  :description "FIXME: write description"
  :url "http://example.com/FIXME"
  :license {:name "Eclipse Public License"
            :url "http://www.eclipse.org/legal/epl-v10.html"}
  :dependencies [[org.clojure/clojure "1.6.0"]
                 [cheshire "5.4.0"]]
  :profiles {:dev
             {:dependencies [[com.cemerick/austin "0.1.5"]
                             [com.cemerick/piggieback "0.1.4-SNAPSHOT"]
                             [ring-mock "0.1.5"]]
              :plugins [[com.keminglabs/cljx "0.5.0"]
                        [com.cemerick/austin "0.1.5"]
                        [lein-cljsbuild "1.0.3"]]
              :test {}}})

Notice how there’s a :dependencies key in the root of the project map and there’s one in the :dev profile.

What this means is whatever is in your currently active profile in your [:profiles :<PROFILE>] will be merged into the root project map.

Therefore, you can merge in dependencies like for say, browser REPLs in your dev profile. Merge in testing related dependencies in your test profile and so forth.


That’s the simple case of leiningen profiles. There’s a lot more you can do in the project.clj file.

Say I was using some library for databases and it was reading the database information from the project.clj map. I could then specify different databases for different environments.

I could have one for development, one for testing that gets rebuilt every time I run tests and so forth.

And this is fine for a single developer team.

What about for teams with multiple people?

This scenario comes up a lot more often then you would think. You could have a coworker that has a mysql database installed locally and another one that has their database installed in a docker container. They would have different connection information, usernames, and passwords.

In this scenario, one solution is to use what I call leiningen overrides.


There exists a file called profiles.clj in your ~/.lein/ directory. You might’ve played with it before if you’re an emacs user to add the cider nrepl middleware to it.

This profile gets loaded for every single leiningen project you work with.

You can override what’s in this folder by going to your project folder, the one that includes project.clj, and create another file named profiles.clj.

That profiles.clj in your project will take precedence over the one in your ~/.lein/ directory.

Also, notice that the map specified in the ~/.lein/profiles.clj file has a :user key (usually). That corresponds to the profile leiningen is using, which defaults to :user.

My ~/.lein/profiles.clj looks like this:

{:user {:plugins [[lein-ancient "0.6.2"]
                  [cider/cider-nrepl "0.9.0-SNAPSHOT"]
                  [lein-create-template "0.1.1"]]}}

Again, just like before, this map gets merged into the project.clj one. The :plugins key isn’t some random key that is specific to the ~/.lein/profiles.clj file. It appears in your project.clj map.

You can add more profiles for each of your environments in your project.clj file or your project’s profiles.clj file.

I make sure every environment my application will run in is defined in the project.clj file and then add overrides in the project’s profiles.clj file.

This is how it’s done:

project.clj

:profiles {:dev-overrides {}
             :dev
             [:dev-overrides
              {:dependencies [[com.cemerick/austin "0.1.5"]
                              [com.cemerick/piggieback "0.1.4-SNAPSHOT"]
                              [ring-mock "0.1.5"]]
               :plugins [[com.keminglabs/cljx "0.5.0"]
                         [com.cemerick/austin "0.1.5"]
                         [lein-cljsbuild "1.0.3"]]}]
             :test-overrides {}
             :test
             [:dev
              :test-overrides]}

There’s a few concepts that need to be explained in this map.

Firstly, by specifying the submap :dev-overrides, which isn’t a special name at all but one I defined myself, I can merge it into other maps in the profiles map.

If you look at the :dev, it’s a vector. The vector has a list of maps that will be merged together. So, by first listing the keyword :dev-overrides, I’m saying, get the value of the keyword :dev-overrides, which in this case is an empty map, and put it here. The next element in the vector is a map, so it merges that with the empty map I had in there originally from :dev-overrides.

With the knowledge that you can merge in maps in the project map, and the knowledge of profiles.clj, you might start to see where I’m going.

Say your project.clj file contains that :profiles map I specified above with the :dev-overrides key. You can now create a profiles.clj file in your project folder like this:

profiles.clj

{:dev-overrides
 {:dependencies [[reagent "0.5.0"]]}}

This is a simple, arbitrary case I came up with where I wanted the dependency reagent to be merged in to my :dev profile locally. Normally you might see things like AWS credentials and so forth, if for instance you’re using weavejester’s env library.

If you’re working with other people, what I would do is make a file called profiles.clj.sample or something and commit that to git. Then when a new developer comes to your project, they can just check it out, rename it to profiles.clj and stick in their own settings to be merged in.

Cider Refresh And Undefining Vars

A neat trick I learned a few months back is that you can reset all of your Clojure namespaces in the repl you’re working on if you’re using Emacs + Cider. Just use M-x cider-refresh.

That command ‘refreshes’ your repl by undefining the vars and reloading them.

This way, if you have run-away code in your repl state, you can refresh it without doing a cider-restart.

This comes in handy especially when you’re writing tests with clojure.test. Let’s say you have a few tests written and delete one. If you evaluate the namespace again, the test you deleted is still defined and will run every time you run the tests in that namespace.

So you have two options. Refresh the namespace or, alternatively, cider-undef the var.

Asset Pipelines in Clojure

When I first started my transition from Ruby on Rails to Clojure, one of the things I missed the most was Sprockets. I had no idea how to compile my assets, minify them, and do all the things Sprockets does for you right out of the box with Rails.

I’ve investigated libraries like Stefon, which is built in Clojure and is closely modeled after Ruby’s Sprockets gem.

At a high level, the problem with Stefon is that the library is trying to force the Rails way into Clojure.

And when you get into using it, you’re likely not going to be able to uberjar with Stefon. I ran into issues with the binaries that were included in the jar that weren’t on the classpath when creating the uberjar.

So Stefon is the wrong tool for the job and is trying to reinvent the wheel.

I think a lot of people, like me, reached for a Clojure specific solution first because coming from Rails, we expected there to be a solution written in the language our application was written in.

Anyway, I even started to roll my own solution a few months back. Then quickly realized, why couldn’t I use another language/platform’s asset compiler? And there was nothing stopping me.

Introducing Gulp.js

Gulp.js is a node.js based streaming asset builder. I highly recommend you use it in your Clojure projects because it’s the right tool for the job (even though you have to write javascript).

In order to get to a process like Sprockets, what you want to do is create cache busting file. These are json files that have your assets and a hash in them so you can cache your assets and not worry about clients not getting the new ones.

From a high level perspective, what you want to do in Clojure after you’ve written your gulpfile is to parse the json out of the file that’s generated by gulp. And you can use that information however you’d like in your web application. You can use it like Sprockets and include all your files before compiling and minifying them, or you can go ahead and use same assets as you’d use in staging and production (minified and combined).

Or, if for some reason you must have a JVM solution, perhaps try my library swiss out. I’ve ran into situations where it wasn’t possible to use a node.js based solution to do asset compilation. Swiss’s development is ongoing and pull requests are welcome.


If you’re looking for a consultant to help your company migrate from Rails to Clojure, send me an email: [email protected]

I have years of Rails and Clojure experience doing web applications.

Intro To Advanced Email Marketing With Behavioral Emails

email icon

Email! Email marketing can make businesses a lot of money. But when people think about email marketing, they usually think of spam.

Of course, real email marketing isn’t spam. Email marketing is permission based marketing. You want to get people’s permission to email them.

People that have already done email marketing will already know this. They’ll also know that the open rates on emails are strictly superior to social media marketing. Tweets get drown out by the other tweets in users’ timelines. Also, people love getting email.

You might be thinking, “But Chris, I hate getting email from businesses. Since I hate getting emails, users will surely hate them too.”

You feel that way for a couple of reasons:

  1. People like us, the geeks, get a lot of email.
  2. The businesses that are sending out these emails are doing it wrong.

I won’t get into why you should be doing email marketing in this post. Just trust me that it makes a lot of money, and much more money than Twitter/Facebook.

This post is on advanced email marketing.

Here’s a small overview of the different levels of email marketing:

  1. None
  2. Email Newsletters
  3. Drip Email Campaigns
  4. Targeted, Behavioral Emails.

We’re going to be talking about behavioral emails, a way to dramatically move the needle on your business, after you’ve done the low hanging fruit of course.

What are behavioral emails?

They go by a few different names, I like to call them behavioral emails because you send emails based on what people do in your app. Sometimes they might be called lifecycle emails.

These emails are a different part of your sales funnel. Newsletters and drip email campaigns are at the top of the funnel. You want to get people to know who you are and trust you to use your product.

Behavioral emails are when people are actually using your app or software.

You’ve seen this type of email before.

Here are some examples:

  • You sign up for a service and they immediately email you to introduce you to the team or founder.
  • You click on a feature and they send you an email telling you how to use it.
  • You leave the app, never to log on again for a week and they email you to “check in” with you.

You can already see how incredibly valuable these emails are.

Behavioral emails improve retention rates, and conversions to paid. Think about it. If a person signs up for your software and forgets to use it, they’ll never come back. But if you remind them, you’ll be able to active more of them into paid users. You can use the same argument for improving retention. Somebody not using the software? Give them an automated ping and you’ll reduce your churn.

How do you send behavioral emails?

Here are two software solutions that let you do this:

Vero and Customer.io.

Either of these services will save you tons of time so you can just focus on writing emails instead of creating the software to do what they already do.

Vero and Customer.io is like a combination of Google Analytics and email marketing. You place a tracking code on your website and your users’ actions are tracked and can be used to trigger emails. No coding other than copying and pasting the code into your website.

If you have a team then I would suggest Vero over Customer.io because they actually have a team management system.

Give it a shot and let me know your results.

An Introduction To Pry, A Ruby REPL

pry

I’m a Ruby, Clojure, and now Node.js developer. When I was doing Clojure, I had a REPL driven development style.

Those of you that don’t know what a REPL is, it’s a read-eval-print-loop. You’ve probably used a REPL before and didn’t even know it. The interactive ruby shell, otherwise known as IRB is the default REPL that ships with Ruby. It’s also the same REPL you get when you run rails console.

The difference between developing in a Lisp like Clojure and a language like Ruby is how integrated the REPL is to how you develop. In Clojure, you get to play with code and mold it.

People that haven’t done this style of development before really should experience it. It’ll change the way you’ll think about programming and your workflow.

When I started doing some Ruby and Rails projects again, I missed having my REPL. Developing with the rails console opened in my terminal and writing methods line by line didn’t cut it.

Enter Pry.

Pry also aims to be more than an IRB replacement; it is an attempt to bring REPL driven programming to the Ruby language. It is currently not as powerful as tools like SLIME for lisp, but that is the general direction Pry is heading.

I first heard about Pry during a job interview at Braintree. I’ve since checked it out and have have integrated it into my workflow.

I’ll start with a simple tutorial to just Pry and since I and many of you are likely to be web developers, how to integrate it with Rails.


The first thing you want to do is install pry by simply running gem install pry.

Pry has many different commands, which are similarly named to the command line utilities you’re already using, like cd and ls.

You can open up a Ruby project you’ve been working on or open up your favorite editor and type this in:

# intro.rb

require 'pry'

puts "Start"

# Start a pry shell
binding.pry

puts "End"

Run the script and you’ll see start, and then the program will pause and you can play with it while it’s running. Basically, the program pauses exactly where you put the binding.pry line so you can do some debugging if necessary.

You can use the shell as if you were to use irb. Enter in 1 + 1 and you’ll get 2 and so forth.

And to exit, simply type exit.

Now here’s the cool part. If you go back to the file and edit it to add in functions, you can hot reload the code.

So, if I were to go and add the function add like so:

require 'pry'

puts "Start"

def add(a, b)  
  a + b
end

# Start a pry shell
binding.pry

puts "End"

You can go back to your repl and type in add(1,2). You’ll see that you’ll have an undefined method error. That’s because we haven’t reloaded the file yet.

Type in reload-code in pry and then you’ll see the file is reloaded and the method add shows up.

Now if you do add(1,2), you can see the return value, which is of course 3.

It gets better when you add in classes. Let’s do that:

require 'pry'

puts "Start"

def add(a, b)  
  a + b
end

class Car  
  attr_accessor :make, :model
  def initialize(make, model)
    @make = make
    @model = model
  end

  def honk
    puts "Beep"
  end
end

# Start a pry shell
binding.pry

puts "End"

Reload the code again in pry.

Again, you can do the same things you can do with irb.

car = Car.new("Tesla", "Model S")  
car.honk

A really cool thing you can do is list all the methods of an object.

Try it:

ls Car

Since we’re listing the methods of the class, we don’t get to see the instance variables. If you were to instead do ls car, using the instance of car we created, you would also get its instance variables outputted.

For help and a list of all commands, type help.

Pry on Rails

Pry Rails is a gem that adds in Rails specific features.

Open up the Gemfile of one of your Rails projects and add this line:

gem ‘pry-rails’, :group => :development

Now your default rails console has been replaced with pry instead of irb.

If you type in help, you’ll see a list of Rails specific commands:

Rails  
  recognize-path     See which route matches a url.
  show-middleware    Show all middleware (that rails knows about).
  show-model         Show the given model.
  show-models        Show all models.
  show-routes        Show all routes in match order.

These commands are significantly faster than running the rake task because the Rails environment is already loaded for you.

Now you can go into your controller and add in the binding.pry line to start pry and it’ll pause the execution of the request at that line and open up the pry shell where you ran rails s. You can now play and debug your application without having to use puts everywhere.