Skip to content
Tabletop Tracker

ADR-0014: WSL2 as the development environment

ADR-0014: WSL2 as the development environment

  • Status: Accepted
  • Date: 2026-07-30
  • Supersedes: —
  • Superseded by: —

Context

The developer’s machine is Windows 11. docs/architecture.md §4 already flags that Wrangler tooling is more reliable on Linux and advises planning for WSL rather than debugging Windows-specific runtime issues.

For an agent-driven build this matters more than usual: a platform quirk that a human recognises and works around in seconds can consume an entire agent loop iteration, and the failure looks like a code bug rather than an environment bug.

Decision

All development, testing and deployment happens in WSL2.

The repository must live inside the WSL filesystem (~/code/tabletop-tracker), not under /mnt/c.

Rationale

Wrangler, Expo and the Docker Postgres of ADR-0011 all sit on well-trodden Linux paths.

The /mnt/c restriction is separate and equally important: cross-filesystem I/O through the 9p protocol is slow, and file-watching is unreliable there. Dev servers miss changes and node_modules operations crawl. Both symptoms present as flaky tooling rather than as a filesystem problem, which is exactly the kind of thing that burns agent iterations.

Consequences

  • WI-001 includes relocating the repository into the WSL filesystem. Doing this first avoids re-treading it later with real work in flight.
  • Docker Desktop must have WSL2 integration enabled for the test database.
  • Editors connect over the WSL remote (VS Code Remote - WSL or equivalent), not to the Windows path.
  • Recorded in AGENTS.md and docs/standards/environment.md, because “just run it on Windows” is the default behaviour this contradicts.

Alternatives considered

Native Windows. No setup cost. Rejected: path, symlink and Wrangler runtime quirks would burn agent iterations on non-problems.

Devcontainer / Docker. Most reproducible and the best story for future collaborators. Rejected for now on setup weight and slower file I/O on Windows hosts. Reconsider if a second developer joins — this decision would be superseded rather than amended.