Working with Nix in libxmtp

Quick Shell Selection

Environment Detection

For agent commands, use dev/nix-shell 'just <recipe>'. The project Codex hook adds this wrapper when trusted. The wrapper caches each evaluated shell environment by the files that the shells read, so a source edit needs no new evaluation; dev/nix-shell --refresh ... evaluates again. Nested calls reuse the same environment only when the worktree, shell, and key match. Do not use the variables below as proof that a requested shell is current. See docs/agent-tools.md.

echo $XMTP_NIX_ENV     # "yes" if in any Rust-based Nix shell
echo $XMTP_DEV_SHELL   # rust, local, android, android-ci, or android-ci-emulator

Critical Constraints

Rust Version is Pinned — Do Not Change

Rust is pinned via flake.nix → rust-manifest (1.97.1 as of 2026-07; check with nix develop .#rust -c rustc --version). All shells use xmtp.mkToolchain. Never modify without project-wide coordination.

Playwright Versions Must Match EXACTLY

The playwright pin in package.json (=X.Y.Z) must equal nixpkgs' playwright version. The js shell provides browsers via PLAYWRIGHT_BROWSERS_PATH (nix/js.nix), and npm playwright looks them up by its own per-version browser revisions — any skew fails WASM tests with browserType.launch: Executable doesn't exist at .../chromium_headless_shell-NNNN/....

After every nixpkgs (flake.lock) bump:

nix eval --raw .#devShells.x86_64-linux.js.PLAYWRIGHT_VERSION
# If it differs from the package.json pin: update the pin, then
# pnpm install

iOS Shell is macOS Only

The .#ios shell only works on Darwin. Requires Xcode 16+ for Swift 6.1.

Untracked Files are Invisible to Flakes

git add <new-file>  # Then rebuild — flakes only see git-tracked files

Cachix

Verify the binary cache is active: nix config show | grep substituters — should include https://xmtp.cachix.org.

Shell Architecture

rust is the core: one Rust toolchain (host, wasm32, the Android ABIs, and on Darwin the Apple slices), the cargo, proto, and lint tools, Node, pnpm, Python 3.11, and just. default layers on it (inputsFrom) with editor, debug, and Swift tools and JDK 21; android takes its core packages and adds the Android SDK, NDK, emulator, JDK 17, Kotlin, and ktlint. All three merge shellCommon.rustShellEnv, so a switch between them changes no compiler variable, and on Darwin all three use Xcode clang with the 11.0 macOS floor.

shell-common.nix   → rustToolchain, rustCorePackages, rustShellEnv, rustShellHook
  ├── rust.nix       → the core (also `wasm`)
  ├── local.nix      → default = rust + local tools (also `ios`)
  ├── android.nix    → core packages + Android SDK and NDK
  └── android-ci.nix → slim CI shells: SDK, NDK, JDK 21; no Rust (Linux only)
js.nix, js-node.nix, docs.nix → JavaScript and docs (no Rust)

Essential Commands

# Enter shells (the wrapper caches each evaluated environment)
dev/nix-shell 'just check'                 # default shell
dev/nix-shell --shell rust 'cargo check'   # Rust core
dev/nix-shell --shell android 'just android check'
dev/nix-shell --refresh true               # evaluate again

# Build packages
nix build .#xmtp-sdk-wasm                    # WASM compiled bindings
nix build .#xmtp-sdk-node-darwin-arm64               # Host-matching .node binary
nix build .#xmtp-sdk-generated                 # Generated JS/TS bindings
nix build .#xmtp-sdk-node-linux-x64-gnu      # Per-target .node (example)
nix build .#android-sdk-libs                     # All Android targets
nix build .#ios-xcframeworks                 # iOS release XCFramework (macOS only)

# Explore
nix flake show           # List all outputs
nix flake metadata       # Show inputs and versions

# Debug
nix develop --show-trace  # Verbose error output

Platform Support

Key Files

Further Reference

• Shell: Default — Full local dev shell reference
• Shell: Rust — Focused Rust shell reference
• Shell: Android — Android shells reference
• Shell: JavaScript — JavaScript shell reference
• Nix Build Packages — All nix build .#<package> outputs
• Troubleshooting — Common issues and solutions