How to Create ClojureScript App

This article is inspired by Create Elm App tool for Elm language, which is in turn inspired by Create React App tool for React.js and JavaScript 🙃

The goal of those tools is to provide build setup with no configuration, so it’s easier to get started for developers and newbies. In this article I’d like to make a short overview of what ClojureScript can offer for those who is just starting with the language.

Leiningen

Leiningen is the easiest way to use Clojure. With a focus on project automation and declarative configuration, it gets out of your way and lets you focus on your code.

That’s it! All you need is a single tool. Leiningen manages your dependencies, runs development server and makes production builds. It is actually the most essential tool for Clojure(Script) projects. It allows to use CSS preprocessors, lint you code, run e2e tests or deploy to production and do much more tasks with plugins. You can think of Leiningen as a task runner like Grunt.

Leiningen eliminates configuration boilerplate using templates. A template is a package written by random person on the internet, to help other developers get started with different types of projects.

Getting started

  1. Install Leiningen (see other installation options):
brew install lein

2. Bootstrap ClojureScript project with Figwheel template:

lein new figwheel project-name
command line output after running `lein new figwheel my-app`

This will generate a project of the following structure:

├── README.md
├── dev
│ └── user.clj
├── project.clj
├── resources
│ └── public
│ ├── css
│ │ └── style.css
│ └── index.html
└── src
└── my_app
└── core.cljs

If you want to start building a web app, you can initialize a project with one of three React.js wrapper libraries: Om, Rum or Reagent.

lein new figwheel project-name -- --rum

Production build

lein cljsbuild once min

lein-cljsbuild is a plugin for building ClojureScript projects.

This will run a task which is defined in the config as min only once and produce optimised and minified production build. The code is optimised by Closure Compiler which is the most advanced JavaScript optimisation tool.

command line output after running `lein cljsbuild once min`

Development server

lein figwheel

lein-figwheel is a plugin for hot-reloading output JavaScript and CSS code.

Let’s have a look on what’s going on here:

  1. Configuration validation. If something is wrong with a config, Figwheel will ask you to fix this by pointing to exact error in config file.
  2. Starting server. Development server is starting at locahost:3449, port can be specified in config.
  3. Compile and watch. Compiles ClojureScript and watching for changes in source files of the project. Figwheel will compile changes and push JavaScript code into browser. If there’s an error in your code, Figwheel will not update it, but instead it will show an alert box in browser with error message and exact location of that error in code.
  4. Starting CSS watcher. Simple watcher for CSS files that will push changes into browser.
  5. ClojureScript REPL. At last Figwheel will start interactive REPL where you can run code that will be executed in browser and interact with project’s code.

I’ve recorded this quick video to show how REPL and Figwheel works.

Dependencies

Clojure(Script) packages are stored in repository similar to NPM, it’s called Clojars. You can find a package there and add it into :dependencies in your project.clj. Leiningen will install new dependencies automatically, when you restart the project.

:dependencies [[org.clojure/core.async "0.2.391"]]

Conclusion

I hope this article will make you less afraid of ClojureScript and help to get started with it in seconds. Below is a list of resources which you might want to read to learn more about language and tools.