Through the lib.app.dev module, a common enhanced application dev experience is provided. Future versions of edge can update the dev experience through this module, without requiring you to update projects to take advantage of them.

1. Setup

If you’ve used the edge app template, you can skip to Quick Start.

Otherwise, you need to:

  1. Make a dev directory

    acme.api$ mkdir dev
  2. Create a dev alias in deps.edn which depends on lib.app.dev and your dev directory.

    :aliases
    {:dev
     {:extra-paths ["dev"]
      :extra-deps
      {juxt.edge/lib.app.dev {:local/root "../lib.app.dev"}}}}
  3. Create dev/log_dev_app.properties with your root namespace. This is used for only showing you logs relating to your application

    acme.api$ echo 'app_root_logger=acme.api' > dev/log_dev_app.properties
  4. Create dev/dev.clj with a boilerplate bringing in lib.app.dev

    (ns dev
      (:require
        [dev-extras :refer :all]))
  5. Create a .dir-locals.el containing your dev jack-in aliases

    ((nil
      (cider-clojure-cli-global-options . "-A:dev:build:dev/build")))

2. Quick Start

Generally REPL session will start like so:

user=> (dev) (1)
dev=> (reset)
:reloading (juxt.edge.demo.foo)
:resumed
  1. This is done automatically when using ../bin/rebel

3. lib.app.dev reference

3.1. dev functions and vars

dev

If you’re in the user namespace, use this to swtich to dev.

user=> (dev)
reset

Use this to start the system, and after making code changes. It will reload your code, and your system.

dev=> (reset)
:reloading (juxt.edge.demo.foo)
:resumed
go

Use this to start the system without reloading your code. You might choose to do this if you’re trying to be quick. But (reset) will result in the same outcome regardless of whether you have already started with (go).

cljs-repl

Use this to switch to a Clojurescript-connected REPL, if you have figwheel available.

add-lib

Use this to hot-load a library into your running environment.

dev=> (add-lib 'hiccup {:mvn/version "2.0.0-alpha1"})
true
system and system-config

These give you insight into the integrant system & configuration. Very useful for debugging.

3.2. Logs

During development, we have crafted a special logging mechanism. It’s based heavily on Stuart Sierra’s log.dev. The design is to show you the relevant information most of the time, and have the rest available one hop away.

All logs from namespaces under your application prefix (set in log_dev_app.properties) are printed to the console. Warning and Error logs from all namespaces are logged to the console too.

Your application’s logs are also written to log/app.log for later reference. All logs from all namespaces are written to log/all.log. These files are rotated to ensure they don’t completely consume your disk over time.

4. Enhanced Shell REPL (Rebel)

There is also a handy ../bin/rebel script, which will launch a repl in any application, using Bruce Hauman’s rebel-readline.

It supports a number of flags, these must be supplied before arguments to clj:

--nrepl

Start an nrepl on port 5600 with CIDER and Refactor pre-configured.

--cljs

Start with clojurescript support for rebel

You use it like so:

acme.app$ ../bin/rebel --cljs -A:dev:build:dev/build
[Edge] Starting development environment, please wait…
[Rebel readline] Type :repl/help for online help info
[Edge] Loading Clojure code, please wait...
[Edge] Now enter (go) to start the dev system
dev=> (reset)
...

5. CIDER jack-in

cider-jack-in will just work provided you create a .dir-locals.el as documented in Setup. This is automatically created with the template.

6. REPLant.nvim

REPLant’s refresh is fully compatible with this setup and will work automatically.