A Leiningen template for projects using Reagent.
Clojure CSS
Clone or download
Latest commit 0f42f8e Aug 9, 2018

README.md

reagent-template

A Leiningen template for projects using Reagent.

reagent-template

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 at the Reagent Google Group.

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, please use lein doo phantom test once. For installation instructions of PhantomJS, please see this.

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

Development mode

To start the Figwheel compiler, 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 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

Deploying to Heroku

Make sure you have Git and Heroku toolbelt installed, then simply follow the steps below.

Optionally, test that your application runs locally with foreman by running.

foreman start

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.

Contents

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
  • Secretary - client-side routing
  • Accountant - additional setup facilities for client-side routing in SPA way
  • Hiccup - server-side HTML templating
  • Compojure - a popular routing library
  • 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

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

Copyright © 2015 Dmitri Sotnikov

Distributed under the The MIT License (MIT).