# figwheel-main keeps a ClojureScript REPL and a live reload loop in one process

> Figwheel Main compiles ClojureScript and hot loads it as you code, with a shared REPL, a heads up display that opens errors in your editor, a static file server and rules that keep unstable code out of the browser. It is a solo maintained project whose last release tag is from 2021.

**bhauman/figwheel-main** — Figwheel Main provides tooling for developing ClojureScript applications

- Repository: https://github.com/bhauman/figwheel-main
- Website: https://figwheel.org
- Stars: 655 · Forks: 88
- Language: Clojure
- License: EPL-1.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/bhauman-figwheel-main

## One process that compiles, serves and hosts the REPL

Figwheel Main builds your ClojureScript code and hot loads it as you code, and the defining decision is that the build process, the development server and the REPL are one thing rather than three. When you launch it, it starts a live building and reloading process and optionally launches a ClojureScript REPL into the running application. That REPL shares compilation information with the ClojureScript compiler, so it knows about the code changes as it happens instead of holding a stale view of the world. It also comes with built-in control functions for the auto-building process and for running build tasks without stopping and rerunning the tool, which is the difference between a REPL you can drive and one that only evaluates expressions. The audience is ClojureScript developers on the JVM toolchain, and the alternatives in the README are honest about the trade, since the author explicitly advises not to spend too long evaluating development environments because the tool space is in constant flux.

## The heads up display turns a compiler error into a click

The heads up display is the feature that most directly changes the day to day work. It is described as non-intrusive, giving feedback on how well the project is compiling, and the clever part is that you can write a shell script so that clicking an error in the display opens it in your editor. In practice that turns a stack trace in a browser overlay into a jump to the offending line in your own editor, which is a bigger workflow change than it sounds. The errors themselves are described as descriptive with code context, pointing to where the problem is in your code, and they show up both in the REPL and in the heads up display. The author also makes configuration errors a first class concern, calling the configuration error reporting excellent and noting that configuring a tool for the first time is daunting. For a project with this many options, a configuration mistake that produces a paragraph of prose instead of a stack trace is a genuine saving.

## Reload rules protect the running page from half-working code

Two behaviours decide what actually reaches the browser, and both are worth understanding before you rely on the loop. The first is that Figwheel will not load a file that has not been required, and it responds to new requirements and to changes in the dependency tree, so the set of loaded namespaces tracks the dependency graph rather than the file system. The second is that if your ClojureScript code is generating compiler warnings, Figwheel will not load it, and the README notes that this behaviour is optional and can be turned off. That is a strict policy by most standards. A warning is not an error, and refusing to hot load code because the compiler emitted a warning will at times stop you from seeing a fix in the browser, particularly if the warning is in a dependency you do not control. On the other hand, it is exactly the rule that keeps a client environment stable while you are halfway through an edit, and the escape hatch is a configuration flag rather than a patch.

## A static file server with an optional ring handler

Figwheel includes a static file server, and the stated reason is speed of setup: it lets you get a ClojureScript development environment up and running quickly without a separate server process. For convenience there is a ring handler option, so you can embed a ring handler into the Figwheel server and serve your own routes from the same process. That matters more as applications grow, because a static file server is enough for a single page app and not enough once you have API calls, and the ring option is the difference between adding another dependency and not. The server also serves as the transport for the live reload channel, and the README notes that changes are broadcast to all connected clients, so you can watch code and CSS changes land on a phone and in a laptop browser at the same time. The connection is described as surviving sessions lasting for days across multiple operating system sleeps, which is a small but real quality of life detail in a tool people leave running.

## Getting a REPL running takes one Clojure CLI invocation

The quick usage path assumes the Clojure CLI tools are installed, with Homebrew given as the way to do that on macOS.

```shell
brew install clojure
```

After that, the README launches a ClojureScript REPL with a single command that pins the dependency inline and starts the main namespace.

```shell
clj -Sdeps "{:deps {com.bhauman/figwheel-main {:mvn/version \"0.2.20\"}}}"  -M -m figwheel.main
```

The described result is that browser REPL code is compiled to a temp directory, a browser opens, and a cljs user prompt appears, at which point REPL driven development of the ClojureScript application can begin. The version number in that example is worth noticing, because it is the coordinate you would copy into your own project. The README also points to a template for a greenfield project, an extensive getting started tutorial, and the ClojureScript quick start for anyone new to the language, with the advice to work in small pieces rather than trying to perfect the development environment first.

## The flappy bird demo shows two entry points, Leiningen and the CLI

The demo project is the fastest way to see the tool working, and the README gives two ways to run it. With Leiningen installed, you clone the demo repository and run the build task.

```shell
$ git clone https://github.com/bhauman/flappy-bird-demo-new.git
```

```shell
$ lein fig:build
```

With the Clojure command line tools, the clone is the same and the run command differs.

```shell
$ clj -A:build
```

That comparison is instructive on its own, since it shows the project supporting both the older Leiningen workflow and the newer Clojure CLI dependency model, which is what a tool that has been maintained across a change in the Clojure ecosystem looks like. The repository tree is consistent with that story. It holds a project.clj for Leiningen and a deps.edn for the CLI tools, plus separate development and documentation setups, a Makefile with sed based version rewriting for the release process, a Clojars badge showing the artifact is published under com.bhauman, and a CHANGES file. The README also points at an introductory blog post, a six minute demo video and a 45 minute talk from ClojureWest 2015, which gives you three different depths of introduction.

## A solo project with a 2021 tag and an explicit warning about the ecosystem

The maintenance record is the thing to weigh. The last push was on 2026-06-21 and the repository is not archived, so the code is still being worked on, but the release list stops at v0.213, published on 2021-04-11 with the note that it contains updates for ClojureScript 1.10.844, ring and webpack 5, before that v0.2.11 and v0.2.10 from 2020. A five year gap between the newest tag and the last push is a strong signal that you are depending on a branch rather than on a release, and the version mismatch shows up in the documentation itself, since the quick usage example pins 0.2.20 while the release list has moved to a 0.213 versioning scheme. The licence is EPL-1.0, which is the usual choice for Clojure libraries and a file-level copyleft scheme worth understanding before you vendor it. The README also says the documentation is currently a good resource but still a work in progress, and it lists where to get help, the ClojureScript Google Group and the clojurescript, figwheel-main and beginners channels on the Clojurians Slack.

## Conclusion

figwheel-main is worth adopting for ClojureScript work where you want a tight edit and reload loop with a REPL attached to the running application, and where the pieces of that loop, the file server, the error display and the REPL, come from one tool rather than four. It is the wrong choice if you want a maintained, actively released build tool, because the newest tag is v0.213 from 2021-04-11 while the last push was on 2026-06-21, and the project itself warns that the Clojure tooling scene is in constant flux. Verify three things before you start a project on it: which ClojureScript version your build pins, since the release notes mention updates for ClojureScript 1.10.844, that the Clojure CLI tools you have work with the dependency coordinates the README shows, and whether the bundled static file server and ring handler options cover what you need, or whether you would rather serve the app yourself. The licence is EPL-1.0.

## FAQ

### How do I start a ClojureScript REPL with figwheel-main?

With the Clojure CLI tools installed, the README shows a single command that pins the dependency inline and starts the main namespace, after which browser REPL code is compiled to a temp directory, a browser opens and a cljs user prompt appears. For Leiningen projects the README shows the lein fig:build task.

### What does the figwheel-main heads up display do?

It is a non-intrusive overlay that shows how well the project is compiling. Because you can write a shell script, clicking an error in the display opens it in your editor, and descriptive compiler errors with code context appear both there and in the REPL.

### Why is my code not being reloaded by figwheel-main?

Two rules can stop a reload. Figwheel will not load a file that has not been required, and it will not load code that is generating compiler warnings, although that second behaviour is optional and can be turned off. Files are also only loaded when the dependency graph requires them.

### Can figwheel-main serve my own application routes?

Yes. It includes a static file server so a development environment can be started quickly, and a ring handler option lets you embed a ring handler into the Figwheel server, so application routes can be served from the same process.

## Sources

- [bhauman/figwheel-main on GitHub](https://github.com/bhauman/figwheel-main)
- [License: EPL-1.0](https://github.com/bhauman/figwheel-main/blob/master/LICENSE)
- [Project website](https://figwheel.org)
- [README](https://github.com/bhauman/figwheel-main/blob/master/README.md)
- [Releases](https://github.com/bhauman/figwheel-main/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/bhauman-figwheel-main