Skip to content

The only tool you need to know what is happening and how to fix it.

chore: add Nix dev shells for backend and frontend (#302)

FrameAutomataf65e7d7f57fb
diff --git a/.envrc b/.envrc
new file mode 100644
index 00000000..0f414d08
--- /dev/null
+++ b/.envrc
@@ -0,0 +1,2 @@
+use flake
+source_env_if_exists .envrc.local
diff --git a/.gitignore b/.gitignore
index 543bf8e3..a41cc767 100644
--- a/.gitignore
+++ b/.gitignore
@@ -72,3 +72,19 @@ skills-lock.json
/.claude/skills
/.agents
/testing/shop/traffic/node_modules
+
+# Nix / direnv dev environment. `nix build` only ever writes its symlink into
+# the working directory, so the result patterns are anchored -- unanchored they
+# would also swallow any future results/ directory or result-*.svelte file.
+.direnv/
+.envrc.local
+/result
+/result-*
+
+# Local databases created by `go run ./cmd/traceway`. SQLITE_PATH defaults to
+# ./traceway.db in the working directory, so these are unanchored to cover
+# running the backend from anywhere in the tree. The .duckdb pair is written by
+# -tags telemetry_duckdb builds. The basename must start with `traceway`, so
+# tracked files like Dockerfile.duckdb are unaffected.
+traceway*.db*
+traceway*.duckdb*
diff --git a/flake.lock b/flake.lock
new file mode 100644
index 00000000..effd00b3
--- /dev/null
+++ b/flake.lock
@@ -0,0 +1,61 @@
+{
+ "nodes": {
+ "flake-utils": {
+ "inputs": {
+ "systems": "systems"
+ },
+ "locked": {
+ "lastModified": 1731533236,
+ "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
+ "owner": "numtide",
+ "repo": "flake-utils",
+ "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
+ "type": "github"
+ },
+ "original": {
+ "owner": "numtide",
+ "repo": "flake-utils",
+ "type": "github"
+ }
+ },
+ "nixpkgs": {
+ "locked": {
+ "lastModified": 1787498568,
+ "narHash": "sha256-9i/VTdusq/+NM/tz+J1Re+ojkMB8MBf0QshnYfzHz30=",
+ "owner": "NixOS",
+ "repo": "nixpkgs",
+ "rev": "56c02bc00adcf003215cc4bd996d6efaf4cff188",
+ "type": "github"
+ },
+ "original": {
+ "owner": "NixOS",
+ "ref": "nixos-unstable",
+ "repo": "nixpkgs",
+ "type": "github"
+ }
+ },
+ "root": {
+ "inputs": {
+ "flake-utils": "flake-utils",
+ "nixpkgs": "nixpkgs"
+ }
+ },
+ "systems": {
+ "locked": {
+ "lastModified": 1681028828,
+ "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+ "owner": "nix-systems",
+ "repo": "default",
+ "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+ "type": "github"
+ },
+ "original": {
+ "owner": "nix-systems",
+ "repo": "default",
+ "type": "github"
+ }
+ }
+ },
+ "root": "root",
+ "version": 7
+}
diff --git a/flake.nix b/flake.nix
new file mode 100644
index 00000000..3c557113
--- /dev/null
+++ b/flake.nix
@@ -0,0 +1,131 @@
+{
+ description = "traceway — error tracking and monitoring platform (backend, frontend, docs)";
+
+ inputs = {
+ nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+ flake-utils.url = "github:numtide/flake-utils";
+ };
+
+ outputs =
+ { nixpkgs, flake-utils, ... }:
+ flake-utils.lib.eachDefaultSystem (
+ system:
+ let
+ pkgs = nixpkgs.legacyPackages.${system};
+
+ # Toolchain versions are derived from the manifests rather than
+ # restated here, so bumping backend/go.mod or frontend/package.json
+ # moves the dev shell with it and the two cannot drift apart.
+ goVersion = builtins.match ".*\ngo ([0-9]+)\\.([0-9]+)\\.[0-9]+.*" (
+ builtins.readFile ./backend/go.mod
+ );
+ go = pkgs."go_${builtins.elemAt goVersion 0}_${builtins.elemAt goVersion 1}";
+
+ frontendPackage = builtins.fromJSON (builtins.readFile ./frontend/package.json);
+ nodeMajor = builtins.head (builtins.match "([0-9]+).*" frontendPackage.engines.node);
+ nodejs = pkgs."nodejs_${nodeMajor}";
+
+ goTools = [
+ go
+ ]
+ ++ (with pkgs; [
+ gopls
+ gotools
+ delve
+ golangci-lint
+ gofumpt
+ govulncheck
+ gotestsum
+ ]);
+
+ jsTools = [ nodejs ];
+
+ sharedTools = with pkgs; [
+ gh
+ git
+ jq
+ just
+ ];
+
+ # The banner is gated on an interactive shell: `nix develop --command`
+ # evaluates the hook too, and an unconditional echo lands on stdout
+ # ahead of the command's own output, so `x=$(nix develop --command ...)`
+ # would capture it. Versions are interpolated at eval time rather than
+ # probed, so entering a shell does not fork go/node.
+ #
+ # Nothing here exports backend configuration: the backend supplies its
+ # own defaults, so a dev shell that set them would only shadow
+ # backend/.env (godotenv.Load never overwrites an already-set variable)
+ # and would drift from the code it duplicates.
+ mkShell =
+ {
+ name,
+ packages,
+ banner ? "",
+ }:
+ pkgs.mkShell {
+ inherit name packages;
+ shellHook = ''
+ if [[ $- == *i* ]]; then
+ echo "traceway dev shell: ${name}"
+ ${banner}
+ fi
+ '';
+ };
+
+ goBanner = ''echo " go ${go.version}"'';
+ nodeBanner = ''echo " node ${nodejs.version}"'';
+
+ goShell = mkShell {
+ name = "backend";
+ packages = goTools ++ sharedTools;
+ banner = ''
+ ${goBanner}
+ echo " run cd backend && go run ./cmd/traceway"
+ echo " duckdb go build -tags telemetry_duckdb ./cmd/traceway"
+ '';
+ };
+ in
+ {
+ devShells = {
+ default = mkShell {
+ name = "default";
+ packages = goTools ++ jsTools ++ sharedTools;
+ banner = ''
+ ${goBanner}
+ ${nodeBanner}
+ echo " commands: see the Quick Start table in CLAUDE.md"
+ '';
+ };
+
+ backend = goShell;
+
+ frontend = mkShell {
+ name = "frontend";
+ packages = jsTools ++ sharedTools;
+ banner = nodeBanner;
+ };
+
+ # cargo builds liboxc_shim.a; the Go toolchain then consumes it via
+ # `go build -tags oxc`. No node — the shim never touches it.
+ oxc = mkShell {
+ name = "oxc";
+ packages =
+ goTools
+ ++ sharedTools
+ ++ (with pkgs; [
+ cargo
+ rustc
+ ]);
+ banner = ''
+ ${goBanner}
+ echo " cargo ${pkgs.cargo.version}"
+ echo " build ./scripts/build-oxc-shim.sh"
+ '';
+ };
+ };
+
+ formatter = pkgs.nixfmt;
+ }
+ );
+}
diff --git a/frontend/package.json b/frontend/package.json
index ab49aeb2..d4bff12e 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -3,6 +3,9 @@
"private": true,
"version": "1.19.20",
"type": "module",
+ "engines": {
+ "node": "22.x"
+ },
"scripts": {
"dev": "vite dev",
"build": "vite build",