fixups

Author: jcscottiii

Makefile

@@ -39,11 +39,16 @@ DOCKERFILES := \
 
 build: gen go-build node-install
 
+# Note: We do NOT use --with-deps here because it fails on newer systems (like Ubuntu 24.04)
+# due to virtual package resolution issues (e.g. libasound2 vs libasound2t64).
 nix-setup: node-install go-install-tools gen
 	npx playwright install
 
 clean: clean-gen clean-node port-forward-terminate minikube-delete
 
+clean-nix:
+	rm -rf .nix/
+
 precommit: license-check  go-fix go-tidy lint test unstaged-changes
 
 ################################
@@ -392,7 +397,7 @@ playwright-install:
 	@if [ -z "$$PLAYWRIGHT_BROWSERS_PATH" ]; then \
 		npx playwright install --with-deps; \
 	else \
-		echo "Skipping playwright install because PLAYWRIGHT_BROWSERS_PATH is set to $$PLAYWRIGHT_BROWSERS_PATH"; \
+		echo "Skipping playwright install because PLAYWRIGHT_BROWSERS_PATH is set to $$PLAYWRIGHT_BROWSERS_PATH. This should have been handled by nix-develop already to prevent sudo prompt."; \
 	fi
 
 playwright-update-snapshots: fresh-env-for-playwright

README.md

@@ -60,6 +60,9 @@ nix develop
 make nix-setup
 ```
 
+> [!NOTE]
+> To clean up the downloaded browsers and start fresh, you can run `make clean-nix`.
+
 ### Running the services locally
 
 After setting up your environment, check out the [DEVELOPMENT.md](./DEVELOPMENT.md) for more information to get started and running locally.

docs/nix-setup.md

@@ -24,9 +24,9 @@ make nix-setup
 
 This will drop you into a new shell with all the required tools in your `PATH`:
 
-- Go (1.26.1)
-- Node.js (24.14.0)
-- OpenJDK 25
+- Go
+- Node.js
+- OpenJDK
 - Terraform, Cloud SDK, Minikube, Skaffold, etc.
 
 You can verify the versions by looking at the output message when you enter the shell.
@@ -107,26 +107,14 @@ Playwright's WebKit browser requires some special handling in a Nix environment
 
 We have handled this in `flake.nix`:
 
-1.  **Correct Library Versions**: We use `libxml2_13` instead of the default `libxml2` because it provides the exact `libxml2.so.2` file WebKit expects, avoiding brittle symlink hacks.
+1.  **Correct Library Versions**: We use `libxml2_13` instead of the default `libxml2` because it provides the exact `libxml2.so.2` file WebKit expects, avoiding brittle symlink hacks. We also added `woff2` to support web fonts.
 2.  **Automatic Patching**: When you enter the shell (`nix develop`), it automatically checks if Playwright browsers are installed in `.nix/browsers`. If found, it patches the `MiniBrowser` wrapper script to preserve your `LD_LIBRARY_PATH` instead of overwriting it.
 
-### Clean Build of the Environment
+### Why we don't use `--with-deps`
 
-If you run into issues with browsers or want to ensure a clean setup:
+We do not use `npx playwright install --with-deps` in `make nix-setup` because it attempts to use the host system's package manager (like `apt`) to install dependencies. On newer Linux distributions (like Ubuntu 24.04), this can fail due to package name changes (e.g., asking for `libasound2` when only `libasound2t64` is available).
 
-1.  **Clean Playwright Cache**: Delete the cached browsers to force a redownload.
-    ```bash
-    rm -rf .nix/browsers
-    ```
-2.  **Re-install Browsers**: Run the install command again (inside `nix develop`).
-    ```bash
-    npx playwright install
-    ```
-3.  **Re-enter Shell**: Exit and re-enter `nix develop` to trigger the automatic patching again!
-    ```bash
-    exit
-    nix develop
-    ```
+By managing dependencies in `flake.nix` and using Nix's environment, we avoid polluting the host system and prevent these distribution-specific installation failures.
 
 ## Playwright E2E Tests and Docker
 

flake.nix

@@ -75,6 +75,7 @@
             libxcursor
             libxml2_13
             libevent
+            woff2
           ];
 
           shellHook = ''
@@ -83,7 +84,7 @@
             export DOCKER_BUILDKIT=1
             export ANTLR=antlr4
             export USE_DOCKER_BROWSER=true
-            export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:${pkgs.libxml2_13.out}/lib:${pkgs.libevent.out}/lib"
+            export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:${pkgs.libxml2_13.out}/lib:${pkgs.libevent.out}/lib:${pkgs.woff2.out}/lib"
             
             # Isolate Playwright browsers to this project
             export PLAYWRIGHT_BROWSERS_PATH="$PWD/.nix/browsers"