Not reviewed yet: this page may be outdated or inconsistent with the other guides. The API reference is generated from the current source.
Getting Started
This guide creates a minimal single-page application with Reagent, using shadow-cljs to compile ClojureScript and npm to provide React.
You need:
- Node.js (includes npm)
- Java 21 or newer, which the ClojureScript compiler runs on
Project files
Create a new directory with the following files:
my-app/
├── package.json
├── shadow-cljs.edn
├── public/
│ └── index.html
└── src/
└── my_app/
└── core.cljs
package.json
React is provided from npm. shadow-cljs is installed as a dev dependency so
that npx shadow-cljs uses the version of this project.
{
"name": "my-app",
"private": true,
"scripts": {
"watch": "shadow-cljs watch app",
"release": "shadow-cljs release app"
},
"dependencies": {
"react": "19.3.0",
"react-dom": "19.3.0"
},
"devDependencies": {
"shadow-cljs": "3.2.1"
}
}
shadow-cljs.edn
The ClojureScript dependencies, including Reagent, are listed here. The :app
build compiles src into public/js/main.js, and :dev-http serves the
public directory at http://localhost:8080.
{:source-paths ["src"]
:dependencies [[reagent "2.0.1"]]
:dev-http {8080 "public"}
:builds
{:app {:target :browser
:output-dir "public/js"
:asset-path "/js"
:modules {:main {:init-fn my-app.core/init}}}}}
public/index.html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>My App</title>
</head>
<body>
<div id="app"></div>
<script src="/js/main.js"></script>
</body>
</html>
src/my_app/core.cljs
Note that the namespace my-app.core lives in the file my_app/core.cljs:
dashes in namespace names become underscores in file names.
(ns my-app.core
(:require [reagent.core :as r]
[reagent.dom.client :as rdomc]))
;; Application state: a Reagent atom. Components that deref it
;; re-render automatically when it changes.
(defonce click-count (r/atom 0))
(defn counter []
[:div
[:p "The button has been clicked " @click-count " times."]
[:button {:on-click #(swap! click-count inc)}
"Click me"]])
(defn app []
[:div
[:h1 "Hello, Reagent!"]
[counter]])
;; React root, created once and reused when the code is reloaded.
(defonce root (rdomc/create-root (js/document.getElementById "app")))
(defn ^:dev/after-load mount []
(rdomc/render root [app]))
(defn init []
(mount))
Components are plain functions that return Hiccup
— vectors describing HTML elements and other components. [counter] uses the
counter component, like <Counter /> in JSX.
init is called once when the page loads (:init-fn in shadow-cljs.edn).
The ^:dev/after-load metadata makes shadow-cljs call mount again after
each code change during development. defonce keeps the state and the React
root across reloads, so the counter value survives code changes.
Running
Install the npm dependencies and start the development build:
npm install
npx shadow-cljs watch app
The first run downloads the ClojureScript dependencies, which takes a while.
Once the build is completed, open http://localhost:8080. Edit core.cljs
and save, and the page updates without a reload.
The watch process also starts an nREPL server (port is written to
.shadow-cljs/nrepl.port) which you can connect to from your editor. See
the shadow-cljs User's Guide
for editor integration.
Building for production
npx shadow-cljs release app
This writes an optimized public/js/main.js. Deploy the contents of public
to any static file host.
Other starting points
reagent-template creates a larger Leiningen project with a Clojure web server, routing, and optional features like tests and CSS compilation:
lein new reagent my-app
Where to go next
- Using Hiccup to Describe HTML
- Creating Reagent Components
- Managing State: atoms, cursors, Reactions, and tracking
- Interop with React — using React components from npm in Reagent, and React Features such as hooks
- The documentation index lists all tutorials and FAQs
- API documentation