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.

Go to the documentation

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.

Command line

$ lein repl

(run)
(browser-repl)

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

Lighttable

Lighttable provides a tighter integration for live coding with an inline browser-tab. Rather than evaluating cljs on the command line with weasel repl, evaluate code and preview pages inside Lighttable.

Steps: After running (run), open a browser tab in Lighttable. Open a cljs file from within a project, go to the end of an s-expression and hit Cmd-ENT. Lighttable will ask you which client to connect. Click 'Connect a client' and select 'Browser'. Browse to http://localhost:10555

View LT's console to see a Chrome js console.

Hereafter, you can save a file and see changes or evaluate cljs code (without saving a file). Note that running a weasel server is not required to evaluate code in Lighttable.

Emacs/Cider

Start a repl in the context of your project with M-x cider-jack-in.

Switch to repl-buffer with C-c C-z and start web and figwheel servers with (run), and weasel server with (browser-repl). Load http://localhost:10555 on an external browser, which connects to weasel, and start evaluating cljs inside Cider.

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.
Unit tests for both Clojure and CLJS. Or you can decide to use Speclj instead, both for CLJ and CLJS. Both specs and CLJS tests can be run in "auto" mode.

Options

--http-kit Use HTTP Kit instead of Jetty
--site-middleware Use the ring.middleware.defaults.site-defaults middleware (session, CSRF), instead of ring.middleware.defaults.api-defaults (see ring.defaults documentation)
--om-tools Use Prismatic's om-tools.dom instead of om.dom
--cljx Using cljx allows you to write code that is shared between Clojure and ClojureScript.
--less Use less for compiling Less CSS files.
--speclj Use speclj test runner for clj and cljs, and disable the core cljs.test tests.

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: How can I get the features in the SNAPSHOT version?
A: Use leiningen's --snapshot flag, e.g. lein new chestnut my-project --snapshot
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 ...).
Q: I just want to compile ClojureScript to fully optimized JavaScript, so I can use it in a static HTML site.
A: Invoke cljsbuild with the uberjar profile active, like this: lein with-profile -dev,+uberjar cljsbuild once, then look for resources/public/js/app.js.
Q: I'm getting CompilerException java.lang.IllegalAccessError: in-seconds does not exist when using Spyscope 0.1.4 or earlier.
A: Upgrade to Spyscope 0.1.5, this issue is caused by an outdated dependency on cljs-time.
Q: I upgraded the version of Om in project.clj, but it seems I'm still using the old version, what's up?
A: If you already did a build before, cljsbuild/figwheel won't pick up on the updated version automatically. Do a lein cljsbuild clean, then start Figwheel again.
Q: The Figwheel output is cluttering up my REPL, can I get rid of it?
A: Not as such, but instead of calling (run), you can call (run-web-server) and (run-auto-reload) in separate repls.

Changelog

v0.7.0-SNAPSHOT-20150130

Added Clojure{,script} unit testing support with Phantom JS. (Rory Gibson)

v0.7.0-SNAPSHOT-20150103

Validate command line arguments
Mention Chestnut version in the generated README
Fix om-tools support
SASSC support has been fixed, but is considered undocumented and unsupported
Update Om: 0.7.0 => 0.8.0-rc1
Add Code of Conduct to generated projects
Update CLJX: 0.4.0 => 0.5.0
Update Clojurescript: 0.0-2496 => 0.0-2644
Fixes for regressions: #71

v0.7.0-SNAPSHOT-20141226

Update Clojurescript: 0.0-2371 => 0.0-2496
Update Compojure: 1.2.0 => 1.3.1
Update Om: 0.7.0 => 0.8.0-beta3
Fixes for regressions: #65 #57

v0.7.0-SNAPSHOT-20141207

Make weasel print both to the REPL and the browser console (Marcus Lewis)
Add support for the LESS CSS pre-processor (Denis Golovnev)
Enable auto-reload of enlive templates in dev mode (Ray H)
Add support for the SASS CSS pre-processor (Edward Wible)
Add suport for Speclj (Edward Wible)
Switch from the deprecated compojure.handler to ring-defaults zakak)
Keep dev dependencies (Leiningen, Figwheel, Weasel, Speclj) out of the Uberjar
Automatically switch the browser-repl to the right namespace after starting up, instead of cljs.user
No longer include lein-ancient, easy enough to add for those that want it
Update Ring: 1.3.1 => 1.3.2
Update Figwheel: 0.1.4-SNAPSHOT => 0.1.6-SNAPSHOT
Update Weasel: 0.4.0-SNAPSHOT => 0.4.2

v0.6.0

Add optional support for CLJX (Olli Piepponen)
Support generation of projects named using the groupId/artifactId convention (e.g. com.example/foo) (Steeve Beliveau)

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.

Documentation