From 9905509f222e400937d2e64ad1fa03a1f257e696 Mon Sep 17 00:00:00 2001
From: Michael Kohl <me@citizen428.net>
Date: Tue, 3 Feb 2026 22:20:47 +0700
Subject: [PATCH] Add flake.nix

---
 .gitignore      |  3 +++
 CONTRIBUTING.md | 14 ++++++++--
 Makefile        | 17 ++++++++-----
 flake.nix       | 68 +++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 93 insertions(+), 9 deletions(-)
 create mode 100644 flake.nix

diff --git a/.gitignore b/.gitignore
index 4052ce21e..a4e5ae24d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -163,3 +163,6 @@ compile_flags.txt
 
 # Local .envrc overrides
 .envrc.local
+
+# nix-direnv artifacts
+.direnv/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 800b09de9..7f5d237cf 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -19,7 +19,7 @@ If you encounter any issues when following along with this file please don't hes
 - [**Doxygen**](https://www.doxygen.nl): For building the C-Reference documentation pages.
 
 
-##### For Linux
+#### For Linux
 
 Before installing the dependencies, you need to add the LLVM repository and GPG key to get Clang 21:
 
@@ -40,7 +40,7 @@ or:
 sudo apt-get install check clang-21 clang-tidy-21 clang-format-21 emscripten doxygen
 ```
 
-##### For macOS (using Homebrew)
+#### For macOS (using Homebrew)
 
 ```bash
 brew bundle
@@ -51,6 +51,16 @@ or:
 brew install check llvm@21 emscripten doxygen
 ```
 
+#### Nix flake
+
+Additionally we provide a `flake.nix` file which includes all dependencies and configuration to easily get started with Herb development. The recommended way to use it is by adding something like the following to `.envrc.local`:
+
+```sh
+use flake . --no-write-lock-file
+```
+
+If you'd prefer to have a  `flake.lock` use `use flake` instead and ignore the lockfile by adding it to `.git/info/exclude`.
+
 ### Building
 
 #### Clone the Repo
diff --git a/Makefile b/Makefile
index 5a1413dfc..674614094 100644
--- a/Makefile
+++ b/Makefile
@@ -67,13 +67,16 @@ ifeq ($(os),Linux)
 endif
 
 ifeq ($(os),Darwin)
-  brew_prefix := $(shell brew --prefix check)
-  test_cflags = $(test_flags) -I$(brew_prefix)/include
-  test_ldflags = -L$(brew_prefix)/lib -lcheck -lm $(prism_ldflags)
-  llvm_path = $(shell brew --prefix llvm@21)
-  cc = $(llvm_path)/bin/clang
-  clang_format = $(llvm_path)/bin/clang-format
-  clang_tidy = $(llvm_path)/bin/clang-tidy
+  llvm_version := 21
+  llvm_prefix ?= $(shell brew --prefix llvm@$(llvm_version))
+  check_prefix ?= $(shell brew --prefix check)
+
+  cc ?= $(llvm_prefix)/bin/clang
+  clang_format ?= $(llvm_prefix)/bin/clang-format
+  clang_tidy ?= $(llvm_prefix)/bin/clang-tidy
+
+  test_cflags = $(test_flags) -I$(check_prefix)/include
+  test_ldflags = -L$(check_prefix)/lib -lcheck -lm $(prism_ldflags)
 endif
 
 all: templates prism $(exec) $(lib_name) $(static_lib_name) test wasm clangd_config
diff --git a/flake.nix b/flake.nix
new file mode 100644
index 000000000..8a35527fe
--- /dev/null
+++ b/flake.nix
@@ -0,0 +1,68 @@
+{
+  description = "Herb";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    flake-utils.url = "github:numtide/flake-utils";
+  };
+
+  outputs =
+    {
+      self,
+      nixpkgs,
+      flake-utils,
+    }:
+    flake-utils.lib.eachDefaultSystem (
+      system:
+      let
+        pkgs = nixpkgs.legacyPackages.${system};
+      in
+      {
+        devShells.default = pkgs.mkShell {
+          packages = with pkgs; [
+            # JavaScript/TypeScript
+            nodejs_22
+            yarn
+
+            # Ruby
+            ruby_4_0
+            bundler
+
+            # Rust
+            rustc
+            cargo
+            clippy
+            rustfmt
+
+            # Java (JNI bindings)
+            jdk17
+
+            # C/C++ toolchain
+            llvmPackages_21.clang
+            llvmPackages_21.clang-tools # clang-format, clang-tidy
+
+            # C testing
+            check
+
+            # WebAssembly
+            emscripten
+
+            # Documentation
+            doxygen
+
+            # Build tools and libraries
+            gnumake
+            libyaml
+            nodePackages."yarn"
+          ];
+
+          shellHook = ''
+            export cc=clang
+            export clang_format=clang-format
+            export clang_tidy=clang-tidy
+            export check_prefix=${pkgs.check}
+          '';
+        };
+      }
+    );
+}