Local Development

Editor setup

IntelliJ IDEA with Cursive

Open the project in IntelliJ IDEA with the Cursive plugin. It will automatically detect the project structure and dependencies and configure the REPL run configuration. We need to slightly update it with additional aliases for dev and test:

1. At the top right corner, open REPL for myproject -> Edit Configurations...

2. Add options -A:user:dev:test and press OK:

3. Now you can run the REPL, execute (reset) in it, and start coding.

VSCode with Calva

Open the project in VSCode with the Calva extension. It will automatically detect the project structure.

1. Start the REPL by running "Calva: Start a Project REPL and Connect (aka Jack-In)":

2. Select deps.edn configuration in the popup:

3. Select dev and test aliases in the next popup:

Now you have the REPL running and can execute (reset) to start the application. To do this, navigate to the dev/user.clj file:

and run the command "Calva: Evaluate Current Form":

The system will start in the REPL:

REPL

The REPL is the main entry point for development. You can run it from the terminal or from your IDE as shown in the previous section. We have preconfigured some convenient commands for you in the dev/user.clj file in the (comment ...) section at the bottom.

Let's look at them:

1. (reset) - starts the application and automatically reloads it on code changes.
2. (stop) - stops the application.
3. (run-all-tests) - runs all tests in the project.
4. (repl-deps/sync-deps) - fetches new dependencies from deps.edn and loads them into the REPL.

mise

This project template uses mise-en-place to manage system dependencies. It's a convenient tool for managing isolated environments for different projects. All system dependency versions are specified in the .mise.toml file. Install them by running:

mise install

This will install all required system dependencies for the project. The first time, you might also need to run mise trust.

Manage project

We use Babashka Tasks for managing the project. View the list of available tasks by executing bb tasks in the terminal:

The following tasks are available:
 
deps           Install all dev deps
clj-repl       Run built-in Clojure REPL
fmt-check      Check code formatting
fmt            Fix code formatting
lint-init      Linting project's classpath
lint           Linting project's code
outdated-check Check outdated Clojure deps versions
outdated       Upgrade outdated Clojure deps versions
test           Run tests
check          Run all code checks and tests
css-watch      Rebuild css on file change in watch mode
css-build      Build minified css
fetch-assets   Fetch static file assets from URLs
build          Build application uberjar
kamal          Deploy application using Kamal

To lint, format code, check all dependency versions, and run tests, use the bb check command, or run other commands individually.

There are two commands to manage CSS files: css-watch and css-build. You don't need to run them manually because the watch-command is already included in the system start in the resources/config.dev.edn file, and the build-command is used in the Dockerfile for production builds.

The project includes a minimal build tool for static files called fetch-assets that downloads files from URLs and places them in the resources/public directory. This helps vendor all static files in the project. To configure which files to download, edit the bb.edn file in the fetch-assets task definition:

fetch-assets {:doc "Fetch static file assets from URLs"
                :requires ([manifest-edn.core :as manifest])
                :task (manifest/fetch-assets!
                        [{:url "https://unpkg.com/htmx.org@2.0.4/dist/htmx.min.js"
                          :filepath "js/htmx.min.js"}
                         {:url "https://cdn.jsdelivr.net/npm/alpinejs@3.14.8/dist/cdn.min.js"
                          :filepath "js/alpinejs.min.js"}])}

Pre-commit git hooks

Running code quality checks before committing or pushing code is convenient. The project intentionally doesn't include this by default as everyone has their own preferences. However, you can easily add it using the excellent tool Lefthook:

1. Install Lefthook by adding it to the .mise.toml file and running mise install:

lefthook = "1.8.2"

2. Create a .lefthook.yml file in the root of the project with the following content:

pre-commit:
  parallel: true
  commands:
    fmt:
      glob: "*.{clj,edn}"
      run: bb fmt-check
    lint:
      glob: "*.{clj,edn}"
      run: bb lint

3. Activate Lefthook by running:

lefthook install

Before your next commit, Lefthook will run the bb fmt-check and bb lint commands if any Clojure or EDN files have been changed.