Valentin Waeselynck edited this page Jun 25, 2016 · 15 revisions

In this tutorial, we'll be building a web app in ClojureScript using mainly Reagent, which is a ClojureScript wrapper for Facebook's React library.

This tutorial was modeled after the official (and quite good) Phonecat Tutorial for AngularJS.

The project

We'll be progressively building an online catalog of phones. You can see the final version here.

The kind of website we're making is a Single Page Application (SPA). Unlike a classical website, in which the client loads HTML pages as the user navigates through the app, in an SPA only one HTML page is actually loaded, after which a script dynamically exchanges data with the server and modifies the DOM, giving the experience of having several logical pages.

SPAs allow for a very fluid an interactive user experience, but they do bring in some technical challenges, notably because they require sophisticated state management; this is where ClojureScript and React's semantics are leveraged.

Prerequisites

This tutorial assumes:

  • you have some familiarity with Clojure(Script) syntax and semantics. If you don't, this comparison with JavaScript may help you, as well as this cheatsheet.
  • you have a basic understanding of how the browser works (HTML, CSS, JavaScript, AJAX, asynchrony, etc.)
  • having read the Reagent home page may help you
  • prior knowledge of React may help, but is not mandatory (I'm the author and I made app with Reagent before even trying React)

You don't need to have done the original Angular tutorial to go through this one.

Following along

This section explains how to set up an interactive development environment so that you can play with the code.

If you only want to read the tutorial, you can skip this section and head straight to Step 0.

Getting set up

To browse and run the code on your local machine, you'll need those installed:

  • Git, the version control system.
  • Leiningen, the popular Clojure project management tool

Downloading the code

To download the full code for the tutorial, run these commands in a terminal window:

git clone https://github.com/vvvvalvalval/reagent-phonecat-tutorial.git
cd reagent-phonecat-tutorial/

In order to get the library dependencies, run the lein deps command in the directory.

The code for each of the 12 steps of this tutorial lives in a branch called step-<n> (from step-0 to step-12 - step-9 is skipped), so all you have to do to edit the code for a particular step is :

git checkout step-<n>

Interactive development

This repository uses Figwheel to provide you a highly interactive development experience, giving you :

  • a ClojureScript REPL (Read Eval Print Loop), which lets you manipulate the app state by hand, experiment with functions, and print documentation.
  • Hot-code reloading, which essentially sends code changes to the browser without erasing the state of your running app.

To start a process which serves your app locally with a REPL and hot-code reloading, run the lein figwheel command in a terminal in the tutorial directory.

From time to time, code changes will be too significant for hot-code reloading to follow. In this case, just refresh your browser tab.

When adding new library dependencies, you'll need to restart the build process. When that happens, just kill your build process by typing Ctrl-C, then run the lein do clean, deps, figwheel command.

Using the REPL

After your REPL fires up, you'll want to move inside the reagent-phonecat.core namespace :

cljs.user => (in-ns 'reagent-phonecat.core)

Now you can type in any ClojureScript code as if you were writing it in your editor. Since your terminal is probably not a great editing environment, you'll probably want to first type your code in your editor, then paste it in the terminal. To ensure you don't break anything in your file when doing this, you may want to wrap this 'REPL-code' in a comment form :

(comment ;; you can safely put any code in here, it will not be evaluated
  (println "hello world")
  (doc reduce)
  (swap state update :phones #(drop 3 %))
)

Let's get started!

Ready to go? It's this way.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.