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.
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 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.
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.
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.
- A ClojureScript interface to Facebook's React. You can choose between
Reagent (default), Om-next (
+om-next), re-frame (+re-frame), Rum (+rum), or use+vanillato do without a React wrapper. - Ring + Compojure. 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. Both specs and CLJS tests can be run in "auto" mode.
General options:
+helpShow an overview of all recognized options, then exit.+no-pollOpt out of usage statistics poll.+http-kitUse HTTP Kit instead of Jetty.+bidiUse bidi instead of Compojure.+site-middlewareUse thering.middleware.defaults.site-defaultsmiddleware (session, CSRF), instead ofring.middleware.defaults.api-defaults(see ring.defaults documentation).+code-of-conduct/+cocAdd the contributor covenant Code of Conduct.+edgeUse the latest available version of all libraries/plugins. This includes alpha/beta versions, but does not include SNAPSHOT versions.+bleeding-edgeLike+edge, but also use SNAPSHOT versions when available.
Choice of UI library:
+vanillaDon't include Reagent, use this if you intend to use some other view library.+om-nextUse om.next, instead of Reagent.+re-frameUse Reagent and re-frame.+rumUse Rum instead of Reagent.
Choice of CSS style:
+lessUse less for compiling Less CSS files.+sassUse SASS for generating CSS.+gardenUse Garden for generating CSS.
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 installNote 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.
- Java 1.7 or later
- Leiningen 2
- Q: How can I get the features in the SNAPSHOT version?
A: Use leiningen's--snapshotflag, 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. Theapp-stateis defined withdefonce, 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: Compile the "min" ClojureScript build, like this:lein cljsbuild once min, then look forresources/public/js/app.js. - Q: I gave my project a very generic name like
cljsorclojureand now it's not working.
A: This is due to namespace clashes. Try picking a more unique name. In particular avoid namespace prefixes used by Clojure, Clojurescript, or existing libraries.
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.
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.
Copyright © 2014-2018 Arne Brasseur
Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent