Home

Awesome

chestnut

Gitter Clojureverse

Clojars Project

<img align="left" alt="Mr. Chestnut" src="resources/chestnut.png">

Getting value out of Chestnut? Consider making a small donation.

Chestnut is a Clojure/ClojureScript application template. It takes the pain out of getting a working ClojureScript setup with live reloading plus a browser connected REPL.

It provides a solid default configuration for a REPL driven workflow, a ClojureScript setup with separate dev/prod/test builds, Figwheel integration, and a basic setup for running CLJ and CLJS unit tests. It provides a basic web backend setup with Compojure, and a frontend based on one of the React wrappers (your choice of Reagent, Rum, om-next, re-frame, or Vanilla JS). It works out of the box on popular cloud providers like Heroku.

While Chestnut it's quite "complete" in a sense, it also tries to be minimal. Boilerplate code is kept to a minimum, and there is only just enough structure to get you started. How you build and structure your app from there is up to you.

Chestnut should appeal to beginners because it allows you to get started quickly and with minimal baggage, it should appeal to more seasoned developers because it provides all the "obvious" configuration for a comfortable setup, without being so opinionated that it becomes a straight jacket.

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.

Need help? Ask on the mailing list (issues on GitHub are for bugs. Feature requests can be done either on the mailing list or on Github.)

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

This README may describe unreleased features, instead you can check the README for the latest stable release

lein new chestnut <name> <options>

e.g.

lein new chestnut my-app +garden +reagent +http-kit

If you're using the snapshot version, then make sure to add a -- to separate Leiningen's and Chestnut's arguments

lein new chestnut my-app --snapshot -- +garden +reagent +http-kit

You can get an overview of all recognized options with

lein new chestnut +help

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

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 (go), 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.

After that it's the regular

(go)
(cljs-repl)

as described above.

List of Contents

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

Options

General options:

Choice of UI library:

Choice of CSS style:

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

FAQ

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.

Other Templates

We hope Chestnut is great for you, but there are also many other templates that tackle similar tasks.. Each has a slightly different perspective, so it is worth taking a look at a few. Here is a comparison chart of many interesting Clojure/ClojureScript templates.

License

Copyright © 2014-2018 Arne Brasseur

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