Liking cljdoc? Tell your friends :D

Quickstart

Install the Wagoe CLI

curl -fsSL https://get.wagoe.org | bash

This installs all prerequisites (JVM, Clojure CLI, Babashka, bbin) and the wagoe command.
Fallback if get.wagoe.org is unavailable:

curl -fsSL https://raw.githubusercontent.com/wagoebv/wagoe/main/scripts/install.sh | bash

Supports macOS, Debian/Ubuntu, Arch Linux, and WSL2. See Installation for manual setup.

Bootstrap a new project

This page is the manual path. Two things do it for you:

bb quickstart, from inside a new project — the command wagoe new prints as your next step. It runs the same eight steps: environment check, configuration, a sample module, migrations.

Or, in Claude Code (or a compatible agentic CLI), the wagoe-setup skill, which starts one step earlier — it creates the project too — and finishes by handing you the URL and admin credentials.

/plugin marketplace add wagoebv/wagoe
/plugin install wagoe@wagoe

Then ask it to set up a new Wagoe project from an empty directory. Both paths run the same commands; keep them in step when either changes.

wagoe new my-app
cd my-app

This scaffolds a complete project with four core modules wired: core, observability, platform, and user.

Add optional modules before starting the system:

wagoe add payments          # PSP abstraction (Stripe / Mollie / Mock)
wagoe add cache             # Redis / in-memory caching
wagoe list modules          # See all 19 optional modules

Run database migrations

clojure -M:migrate up

Naming, safe patterns and recipes are in Database Migrations.

Start the system

source .env          # wagoe new already generated this with a real JWT_SECRET
clojure -M:repl
wagoe new writes a .env (git-ignored) containing a generated JWT_SECRET — no need to export one by hand. source .env (or direnv allow) loads it into the shell.

clojure -M:repl starts a headless nREPL server on port 7888. Connect your editor (or the Wagoe MCP server) to it, then eval:

(go)
;; => System started. Visit http://localhost:3000

;; After changing code:
(reset)

;; Full restart (after defrecord changes):
(halt)
(go)

Scaffold your first module

The interactive wizard is the standard way to create a module:

bb scaffold

If you want the same result without prompts, use the generated command directly. For example, a product module:

bb scaffold generate \
  --module-name product \
  --entity Product \
  --field name:string:required \
  --field sku:string:required:unique \
  --field price:decimal:required

bb scaffold integrate product

# Apply the generated migration
clojure -M:migrate up

Then reload the system so the new routes are live:

(reset)
curl http://localhost:3000/api/v1/products
# => []

[] is the right answer: the generated handlers are stubs that return canned responses, and wiring them to the service is your first edit. The routes live in src/<your-project>/product/shell/http.clj — bb scaffold integrate prints the prefix they are mounted under.

For a browsable CRUD UI over your tables rather than a JSON stub, add the admin module:

wagoe add admin
bb create-admin       # it requires a signed-in admin, and a new project has none

Restart, then open http://localhost:3000/web/admin/. See the admin reference for choosing which entities it manages.

Run tests

clojure -M:test
clojure -M:test --focus-meta :unit

When something is wrong

One command, and it ends with the single thing to fix:

wagoe doctor

It runs four checks in the order their answers depend on each other — environment prerequisites, configuration, commands and aliases, project setup — and stops early when a foundational one fails, because everything after it would report the same problem in three more ways.

Each of those is still its own bb task (bb doctor:env, bb doctor, bb smoke-check, bb guide next), and CI calls them directly with --ci. You do not have to know which is which; wagoe doctor is the front door.

For questions rather than failures, bb guide is a set of topic guides written for this framework:

bb guide                  # list the topics
bb guide scaffold         # generating a module
bb guide testing          # the test pyramid and what goes where
bb guide database         # migrations, seeds, adapters
bb guide fcis             # what may live in core/ and what may not
bb guide config           # config.edn, profiles, #env
bb guide next             # what to do next in this project
bb guide error BND-201    # what an error code means, and the fix

bb check is a different thing: code-quality gates for code you have written, not setup diagnostics.

Next steps

  • Your First Module - see what the scaffolder generated

  • Key Concepts - learn the rules once, then reuse them everywhere

  • Functional Core / Imperative Shell - the pattern behind everything

  • Testing - unit, integration, and contract tests

❮InstallationWhy Wagoe?❯

Can you improve this documentation? These fine people already did:
Thijs Creemers & thijscreemersEdit on GitHub

cljdoc builds & hosts documentation for Clojure/Script libraries

Keyboard shortcuts
Ctrl+kJump to recent docs
←Move to previous article
→Move to next article
Ctrl+/Jump to the search field
Raise an issueBrowse cljdoc sourceChat on Slack
× close