Skip to content

clj-nix

Nix helpers for Clojure projects

STATUS: alpha.

Introduction

The main goal of the project is to reduce the friction between Clojure and Nix. Nix is a great tool to build and deploy software, but Clojure is not well supported in the Nix ecosystem.

clj-nix tries to improve the situation, providing Nix helpers to interact with Clojure projects.

The main difficulty of packaging a Clojure application with Nix is that the derivation is restricted from performing any network request. But Clojure makes network requests to resolve the dependency tree. Some network requests are done by Maven, since Clojure uses Maven under the hood. On the other hand, since git deps were introduced, Clojure also accesses the network to resolve git dependencies.

A common solution to this problem are lock files. A lock file is a snapshot of the entire dependency tree, usually generated the first time we install the dependencies. Subsequent installations will use the lock file to install exactly the same version of every dependency. Knowing beforehand all the dependencies, we can download and cache all of them, avoiding network requests during the build phase with Nix.

Ideally, we could reuse a lock file generated by Maven or Clojure itself, but lock files are not popular in the JVM/Maven ecosystem. For that reason, clj-nix provides a way to create a lock file from a deps.edn file. Creating a lock file is a prerequisite to using the Nix helpers provided by clj-nix.

Goals

  • Create a binary from a Clojure application
  • Create an optimized JDK runtime to execute the Clojure binary
  • Create GraalVM native images from a Clojure application
  • Simplify container creation for Clojure applications
  • Run any arbitrary Clojure command at Nix build time (like clj -T:build or clj -M:test)

Getting Started

  • For new projects, start with the Usage guide to create a project from the template.

  • For detailed examples, see the Tutorial which walks through creating binaries, custom JDKs, and containers.

  • For a complete API reference, see the API documentation.

Forking this project

To ensure the GitHub Actions workflow is working, you will need to create your own CloudFlare account and a "CloudFlare Pages" project called: clj-nix with the following API call:

CLOUDFLARE_ACCOUNT_ID=""                  # Your Cloudflare Account ID
CLOUDFLARE_API_TOKEN=""                   # API token with "Pages Write" permission
CLOUDFLARE_PAGES_PROJECT_NAME="clj-nix"   # CloudFlare Pages project name

# Create the Pages project
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/pages/projects" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    -d '{ "name": "'$CLOUDFLARE_PAGES_PROJECT_NAME'", "production_branch": "main" }' \
    | jq .

Then, in this section of the project's GitHub page: Settings > Secrets and variables > Actions Create the following Repository secrets: * CLOUDFLARE_ACCOUNT_ID * CLOUDFLARE_API_TOKEN

And the GitHub Action workflow for the documentation should execute successfully.

Similar projects