Getting started

A BigConfig Package (announcement) is a standard Clojure project. Its core logic is defined as a function authored via the BigConfig Workflow .

Scaffold a BigConfig Package Kickstart your project quickly using our official starter template.

Requirements

BigConfig leverages Clojure and Babashka . Since BigConfig does not ship with a dedicated CLI, you will use Babashka and Clojure Tools to interact with your packages from the terminal.

Homebrew
Nix

brew install clojure/tools/clojure
brew install borkdude/brew/babashka

nix profile add nixpkgs#clojure
nix profile add nixpkgs#babashka

Using with Babashka

To use a package, add it as a dependency in your bb.edn and map it to a Babashka task.

Add the package to your :deps and define a task that calls the package entry point:

;; bb.edn
{:deps {io.github.amiorin/alice {:git/sha "9c214edce47419297e6bd8212a63bb0ab93bcf86"}}
 :tasks
 {:requires ([io.github.amiorin.alice.package :as package])
  alice {:doc "Manage the Alice package"
         :task (package/alice* *command-line-args*)}}}

Execute via CLI

Standardize your lifecycle commands using the registered task. Note that we use create rather than install to reflect that infrastructure is actively provisioned during delivery.
Terminal window
```
# Provision infrastructure and software
bb alice create

# Tear down the resources
bb alice delete
```
Performance Note: Because BigConfig leverages Babashka, startup times are near-instant. This makes it ideal for both CI/CD pipelines and fast developer “inner-loop” iterations.

Development Workflow

To develop or debug a package locally, clone the repository and update your bb.edn to point to the local path:

{:deps {io.github.amiorin/alice {:local/root "../path/to/cloned/repo"}}
 :tasks
 {:requires ([io.github.amiorin.alice.package :as package])
  alice {:doc "Local Alice development"
         :task (package/alice* *command-line-args*)}}}

Available Steps

Lifecycle Steps

Step	Description
`create`	Initiates the delivery and provisions resources.
`delete`	Destroys the delivery and cleans up resources.

Coordination Steps

These client-side steps provide functionality similar to Atlantis for Terraform, allowing for safe coordination in shared environments.

Step	Description
`git-check`	Ensures the working directory is clean and synced with origin.
`git-push`	Pushes local commits to the remote repository.
`lock`	Acquires an execution lock to prevent concurrent runs.
`unlock-any`	Force-releases the lock, regardless of the current owner.

Passing Options

Users can pass custom configuration options directly to the package via the task definition:

;; bb.edn
{:deps {io.github.amiorin/alice {:git/sha "9c214edce47419297e6bd8212a63bb0ab93bcf86"}}
 :tasks
 {:requires ([io.github.amiorin.alice.package :as package])
  alice {:doc "Alice with prod profile"
         :task (package/alice* *command-line-args* {:big-config.render/profile "prod"})}}}

Note: bb.edn does not support the :: auto-resolved keyword notation used in standard Clojure files. Use full strings or qualified keywords.

Advanced Usage: Overriding Workflows

If you need to dynamically generate options or override step-fns (middleware), you can wrap the existing workflow function.

(ns io.github.new-user.alice.package
  (:require
   [big-config :as bc]
   [big-config.render :as render]
   [big-config.workflow :as workflow]
   [io.github.amiorin.alice.package :as p]))

(defn alice*
  [args & [opts]]
  (let [profile "default"
        ;; Custom middleware/logic can be injected here
        step-fns [(fn [f step opts] (f step opts))]
        opts (merge (workflow/parse-args args)
                    {::bc/env :shell
                     ::render/profile profile
                     ::workflow/prefix (format ".dist/%s" profile)}
                    opts)]
    (p/alice step-fns opts)))

Then, point your bb.edn to your local wrapper:

{:deps {io.github.new-user.alice {:local/root "."}}
 :tasks
 {:requires ([io.github.new-user.alice.package :as package])
  alice (package/alice* *command-line-args*)}}