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

Chestnut is a Leiningen template for a Clojure/ClojureScript app based on Om or Reagent, 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.

Need help? Ask on the mailing list (please do not open an issue 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.

Go to the documentation

lein new chestnut <name>

After that open the README of your generated project for detailed instructions, or consult the Documentation

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:3449

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.

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:3449 on an external browser, which connects to weasel, and start evaluating cljs inside Cider.

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.
• Om ClojureScript interface to Facebook's React. Alternatively you can use Reagent (--reagent), or use --vanilla to do without a React wrapper.
• 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. Both specs and CLJS tests can be run in "auto" mode.

• --reagent Use Reagent instead of Om
• --vanilla Don't include Om, use this if you intend to use some other view library
• --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)
• --less Use less for compiling Less CSS files.

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

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.

• Java 1.7 or later
• Leiningen 2

• 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: Compile the "min" ClojureScript build, like this: lein cljsbuild once min, 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.
• Q: I gave my project a very generic name like cljs or clojure and 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.

• Add cljc support
• ClojureScript 1.9.89
• Figwheel 0.5.4-4

• Clojurescript 1.9.36
• Include Transit for faster ClojureScript compilation
• Figwheel 0.5.4-2
• Reagent 0.6.0-rc
• Om 1.0.0-alpha36

• Avoid using Leiningen profile merging for :cljsbuild configs

• Upgrades
  • org.omcljs/om 1.0.0-alpha31 => 1.0.0-alpha35
  • lein-auto 0.1.1 => 0.1.2
  • lein-less 1.7.3 => 1.7.5
  • org.clojure/clojurescript 1.8.40 => 1.8.51
  • environ 1.0.2 => 1.0.3
  • lein-cljsbuild 1.1.1 => 1.1.3
  • lein-environ 1.0.1 => 1.0.3
  • figwheel 0.5.2 => 0.5.3-2
• Only add "dev" to the classpath in dev mode, fixes an issue with lein jar

• Upgrade ClojureScript 1.7.228 => 1.8.40
• Upgrade Figwheel 0.5.1 => 0.5.2

• Fix missing dependency when using --http-kit

• Add switches for --reagent and --vanilla
• Upgrade Figwheel to 0.5.1
• Upgrade to Clojure 1.8.0, Om 1.1.0-alpha31, ring-defaults 0.2.0, compojure 1.5.0

• Upgrade Figwheel to 0.5.0-6
• Upgrade Environ to 1.0.2
• Upgrade internal dependencies to play better with Boot

• Use Figwheel for REPL and Ring server
• Remove boilerplate that's no longer needed
• Drop Enlive and simplify the dev setup
• Drop CLJX support
• Better inline documentation
• Upgrade all dependencies

• Version upgrades: clojurescript: 1.7.145 => 1.7.189, om: 1.0.0-alpha15 => 1.0.0-alpha28, figwheel => 0.4.1, figwheel-sidecar 0.4.1 => 0.5.0-2, lein-figwheel 0.4.1 => 0.5.0-2
• Version upgrades: clojurescript: 1.7.122 => 1.7.145, om: 0.9.0 => 1.0.0-alpha15, tools.nrepl => 0.2.12, figwheel => 0.4.1, figwheel-sidecar => 0.4.1, lein-figwheel => 0.4.1,environ => 1.0.1, lein-environ => 1.0.1
• Fix allowing projects to have - in their names.
• Fix allowing groupID/artifactID naming convention.
• Fix "No such namespace" when using om via the REPL.
• Fix specljs auto testing.
• Added gzip compression using ring.middleware.gzip.
• Added browser cache-control hinting using ring.middleware.browser-caching.
• Version upgrades: clojure: 1.6.0 => 1.7.0, clojurescript: 0.0-3058 => 1.7.48, ring: 1.3.2 => 1.4.0, ring-defaults: 0.1.4 => 0.1.5, compojure: 1.3.2 => 1.4.0, om: 0.8.8 => 0.9.0, figwheel: 0.2.5 => 0.3.7, piggieback: 0.1.5 => 0.2.1, weasel: 0.6.0 => 0.7.0

• Restore working lein repl for cljx projects (Josh Daghlian)
• Use latest version of enlive to fix windows issue (Justin Squirek)

• Update Om: 0.8.0-rc1 => 0.8.8 (Anna Pawlicka)
• Make Uberjar executable (Børge Svingen)
• Remove react.js injection in dev html (Jamie English)
• Fix how Less and Sassc are invoked (Daryl Lau)
• Fix in figwheel config (Tim Gilbert), (Philip Joseph), (Antony Woods)
• Fix in test setup (Geoff Shannon)
• Doc fixes (Anthony Rosequist)
• Version upgrades: clojurescript: 0.0-2511 => 0.0-3058 ; figwheel: 0.2.1-SNAPSHOT => 0.2.5 ; weasel: 0.4.2 => 0.6.0 and more

• Added Clojure{,script} unit testing support with Phantom JS. (Rory Gibson)
• Update om-tools: 0.3.9 => 0.3.10
• Update ring-defaults: 0.1.2 => 0.1.3
• Use figwheel-sidecar, drop the dependency on leiningen
• renamed the per-env namespace from dev to main
• give a proper error message when trying to invoke less in production

• 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

• 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

• 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

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

• 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

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

• 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)

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

• First release, containing Austin, Figwheel, Om

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.

Copyright © 2014-2016 Arne Brasseur

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