reagent-template

A Leiningen template for projects using Reagent.

A Leiningen template for a Clojure/ClojureScript app based on Reagent, with a focus on providing a batteries included setup for development and deployment.

Requires JDK 1.7+

Getting Help

For any questions or discussion please come join us in the #reagent channel on the Clojurians Slack.

Usage

Create a new application project:

lein new reagent <name>

To enable cljs.test and doo use +test flag:

lein new reagent <name> +test

To run the tests using headless chrome first install karma and its plugins npm install -g karma-cli && npm install karma karma-cljs-test karma-chrome-launcher --save-dev, then use lein doo chrome-headless test once. For other environments please check doo's documentation.

To enable speclj with PhantomJS, use +spec flag:

lein new reagent <name> +spec

To run the tests, please use lein cljsbuild test. For installation instructions of PhantomJS, please see this.

To enable DevCards, use the +devcards flag:

lein new reagent <name> +devcards

To add CIDER plugin, use the +cider flag:

lein new reagent <name> +cider

To add less/sass support use +less or +sass flags:

lein new reagent <name> +less

To add figwheel (legacy), use the +figwheel flag:

lein new reagent <name> +figwheel

Development mode with shadow-cljs

To start the shadow-cljs compiler run

npm install
shadow-cljs watch app

Shadow-cljs automatically pushes cljs changes to the browser. The application will now be available at http://localhost:3000.

Development mode with Figwheel

To start the Figwheel compiler (if enabled with +figwheel flag), navigate to the project folder and run the following command in the terminal:

lein figwheel

To start the DevCards (if enabled with +devcards flag) build run

lein figwheel devcards

Figwheel will also automatically push cljs changes to the browser. The server will be available at http://localhost:3449 once Figwheel starts up. To view your devcards, type (switch-to-build devcards) at the Figwheel REPL and navigate to http://localhost:3449/cards.

Figwheel also starts nREPL using the value of the :nrepl-port in the :figwheel config found in project.clj. By default the port is set to 7002.

The figwheel server can have unexpected behaviors in some situations such as when using websockets. In this case it's recommended to run a standalone instance of a web server as follows:

lein do clean, run

The application will now be available at http://localhost:3000.

In case of using +less option you may also want to run

lein less4j auto

to autocompile less files.

In case of using +sass option you may also want to run

lein sass4clj auto

to autocompile sass/scss files.

Optional development tools

Start the browser REPL:

$ lein repl

The Jetty server can be started by running:

(start-server)

and stopped by running:

(stop-server)

Building for release

lein do clean, uberjar

Building for release with shadow-cljs

shadow-cljs release app

Deploying to Heroku

The project generates a system.properties used for Heroku deployments. Make sure you have Git and Heroku toolbelt installed, then simply follow the steps below.

Optionally, test that your application runs locally by running.

lein do clean, uberjar
heroku local

Now, you can initialize your git repo and commit your application.

git init
git add .
git commit -m "init"

create your app on Heroku

heroku create

optionally, create a database for the application

heroku addons:add heroku-postgresql

The connection settings can be found at your Heroku dashboard under the add-ons for the app.

deploy the application

git push heroku master

Your application should now be deployed to Heroku! For further instructions see the official documentation.

The template packages everything you need to create a production ready ClojureScript application following current best practices. The template uses the following features and libraries:

Reagent - ClojureScript interface to Facebook's React
reagent-forms - data binding library for Reagent
reagent-utils - utilities such as session and cookie management
Reitit - Routing, server and client side
Accountant - HTML5 history management, enabling href navigation in SPAs
Clerk - In page navigation for SPAs. Scroll restoration, anchor targeting, and such.
Hiccup - server-side HTML templating
Ring - Clojure HTTP interface
Prone - better exception reporting middleware for Ring
Heroku - the template is setup to work on Heroku out of the box, simply run git push heroku master

Options

The template supports the following options:

+test - ClojureScript testing support
+spec - use speclj for TDD/BDD
+less - use less for compiling Less CSS files
+sass - use sass for compiling Sass/Scss CSS files
+devcards - add Devcards support
+cider - add CIDER support
-clerk - do not add Clerk support

Contributing & Customizing

Take a look at the open issues, especially ones marked as help wanted. If you see one you'd like to address don't hesitate to start a discussion or submit a pull request.

If the template isn't doing quite what you're looking for, it's easy to create a local copy of your own following these simple steps:

git clone https://github.com/reagent-project/reagent-template.git
cd reagent-template
lein install

If you feel that your customizations are general enough to be useful for others then please consider making a pull request.

Requirements

JDK 1.7+
Leiningen 2.x

License

Distributed under the The MIT License (MIT).

thheller/reagent-template