chestnut

A Leiningen template for a Clojure/ClojureScript app based on Om, featuring a great dev setup, and easy deployment.

For smooth development you get instant reloading of Clojure, ClojureScript, and CSS. A browser-connected REPL is also included.

For deployment you get uberjar support, meaning you can get all your code compiled, optimized, and packaged in a single executable JAR file. It also contains the necessary artifacts to work on Heroku out of the box.

This README may describe unreleased features. Please compare the version number on Clojars to the changelog below, and check the README in your generated project for instructions pertaining to your version.

Usage

lein new chestnut <name>

After that open the README of your generated project for detailed instructions.

tl;dr

$ lein repl

(run)
(browser-repl)

Wait a bit, then browse to http://localhost:10555.

List of Contents

This template gives you everything you need to start developing Clojure/ClojureScript apps effectively. It comes with

Figwheel Automatically reload your ClojureScript and CSS as soon as you save the file, no need for browser refresh.
Weasel Next generation browser connected REPL. Try things out and manipulate your running app.
Om ClojureScript interface to Facebook's React.
Ring Clojure's de facto HTTP interface. Chestnut uses a Jetty or HttpKit server to serve the Clojurescript app. This way you already have an HTTP server running in case you want to add server-side functionality. Chestnut also inserts a Ring middleware to reload server-side Clojure files.
Heroku support. Chestnut apps have all the bits and pieces to be deployable to Heroku. Getting your app on the web is as simple as git push.

Options

--http-kit Use HTTP Kit instead of Jetty
--site-middleware Use the compojure.handler.site middleware (session, CSRF), instead of compojure.handler.api (see compojure.handler documentation)
--om-tools Use Prismatic's om-tools.dom instead of om.dom

Use -- to separate these options from Leiningen's options, e.g. lein new chestnut foo -- --om-tools --http-kit

Local copy

If you want to customize Chestnut, or try unreleased features, you can run directly from master like this:

git clone https://github.com/plexus/chestnut.git
cd chestnut
lein install

Note that master may be partially or wholly broken. I try to do extensive manual testing before releasing a new stable version, so if you don't like surprises then stick to the version on Clojars. Issue reports and pull requests are very welcome.

Requirements

Java 1.7 or later
Leiningen 2

FAQ

Q: I'm seeing warnings while compiling ClojureScript. A: There are a few known warnings, but they should not affect the functioning of your app.
Q: I changed the {:text "Hello Chestnut!"} portion and saved the file, but the changes don't show up. A: It's a feature. The app-state is defined with defonce, so your application state doesn't reset every time you save a file. If you do want to reset after every change, change (defonce app-state ..) to (def app-state ...).

Changelog

v0.5.0

Run figwheel inside (run) so we only need one process
Configure figwheel's CSS reloading and load a placeholder style.css
Refresh Om when Figwheel reloads
Update ClojureScript: 0.0-2342 => 0.0-2371
Update Compojure: 1.1.9 => 1.2.0
Update Om: 0.7.1 => 0.7.3
No longer depend on Weasel in production mode

v0.4.0

Option to switch to HTTP Kit for a web server
Add reloading middleware
Add default compojure.handler.site middleware

v0.3.0

Switched to Weasel for Austin
Optimized uberjar
Fix usage of {{name}}/{{sanitized}}
Load react from the jar, instead of from Facebook's CDN
Update dependencies (Clojurescript, Ring, Compojure, Environ)

v0.2.0

Uberjar support
Heroku support (Procfile, system.properties)
added .gitignore
First version of development/production modes

v0.1.0

First release, containing Austin, Figwheel, Om

Sources

I used the browser-connected-repl that's included with Austin as a starting point, then pulled in bits from cljs-liveedit-webapp until things worked. Figwheel's Flappy Bird Demo app also provided some ideas. The concept of refreshing Om when Figwheel reloads was taken from this blog post by Michiel Borkent.

For Heroku support I looked at Heroku's clojure-getting-started example app.

License

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.

sunkencity/chestnut