Development

Development

One of the main goals of this project is to provide the best possible development experience. Clojure developers expect to be able to modify code in a running application and the same should be true when working with ClojureScript.

Many people have complained about ClojureScript adding a compile step to JavaScript development. This is a valid complaint. In JavaScript, we are used to making changes and reloading the browser to see their effect. With ClojureScript, we can do even better.

ClojureScript One provides an environment where page reloads will reload ClojureScript code and Clojure code if any changes have been made. In addition to this, there is also a browser-connected REPL which allows you to make changes to a running application.

This project uses its own reloading scheme which is implemented in src/lib/clj/one/reload.clj. You may configure a list of Clojure files to watch for changes. If any file changes all of the watched files will be reloaded. If any ClojureScript file changes, or if any HTML template file changes, every ClojureScript file will be reloaded.

The specific Clojure files which are watched and reloaded can be configured in the one.sample.config namespace.

Reloading only the files that change is problematic. For example, if a macro from one file is used in another, and the macro implementation is changed, both files will need to be reloaded. If a protocol from one file is changed and another file implements this protocol, both files need to be reloaded. To keep things simple, this project will reload everything.

Reloading ClojureScript files when HTML templates change means that when you update an HTML file, the change is immediately visible in the ClojureScript application when the page is reloaded.

Most of the time, we don't need to resort to reloading the entire page because it is easy to add and update functions from the REPL. Reloading the page is most helpful when we are simultaneously making changes to the client and the server or we are modifying templates.

Browser-connected REPL

As briefly mentioned above, Clojure developers are used to making modifications to a running program. The REPL is not only used to experiment with existing code, but is also used to add new functions and modify existing functions. In a normal workflow, all development goes through the REPL.

To see just how interactive this can be, start the ClojureScript REPL as described on the Quick Start page and follow along with the examples below.

The example application provides a simple form which displays a greeting. As the state of the application changes, views which display the state are rendered. We can test this from the REPL:

(in-ns 'one.sample.model)
(swap! state assoc :state :greeting :name "James")
(swap! state assoc :state :init)

The state atom contains the state of the application. When the atom is updated, the views respond. These two state changes illustrate what happens in the view when valid data is entered and when the application is initialized.

The sample application uses an event dispatcher to fire and react to events. We can try adding new reactions and firing events from the REPL:

(in-ns 'one.sample.view)
(def alert-reaction (dispatch/react-to #{:greeting} (fn [_ d] (js/alert (str "Hello " (:name d))))))
(dispatch/fire :greeting {:name "Jim"})
(dispatch/fire :init)

With this new reaction in place, an alert will be displayed when the form is submitted.

Individual reactions can be removed. The call to dispatch/react-to returns the reaction which represents the association of an event to a reactor. The dispatch/delete-reaction function can be used to remove an individual reaction.

(dispatch/delete-reaction alert-reaction)
(dispatch/fire :greeting {:name "Jim"})
(dispatch/fire :init)

To remove all of the REPL code from the runtime environment, refresh the page.