Skip to content

development.md

Latest commit

 

History

History
152 lines (108 loc) · 5.56 KB

development.md

File metadata and controls

152 lines (108 loc) · 5.56 KB
Raw

Development

First checkout

Install vp using the root README. The checkout requires Node 24; Bun is optional. From the repository root:

vp i
vp run dev

Open the one-time pairing URL printed by the dev runner. The bare origin does not authenticate a new browser.

Choosing a dev process

Use vp run dev for server and web, or vp run dev:desktop for the Electron client. dev:server and dev:web start those processes separately. See the mobile README for native builds and Metro.

Flags go directly after the task name, for example vp run dev --home-dir /tmp/t3code-dev. Add --browser to open a browser automatically.

State and ports

Linked worktrees default to their own .t3/userdata, even when T3CODE_HOME is set. The main checkout defaults to ~/.t3/dev/userdata. An explicit --home-dir wins in both cases. Never run a development server against the live ~/.t3/userdata. See test data for copying a consistent database snapshot.

Read ports from the [dev-runner] output. Worktrees derive stable preferences from their paths, but occupied ports can shift them. T3CODE_PORT_OFFSET or T3CODE_DEV_INSTANCE can select a different preference when needed.

Sharing and remote debugging

vp run dev --share publishes the web port over the machine's tailnet and prints a pairing URL for that origin. Give the tester the complete URL, including its token. The dev runner removes its mapping on exit.

Leave VITE_HTTP_URL and VITE_WS_URL unset. Vite proxies the backend through the browser's origin so the same build works over localhost and remote connections.

Shared runs enable bundled dev to avoid a network round trip for each import level. T3CODE_BUNDLED_DEV=0 opts out when debugging bundler differences. Two reload traps matter when changing this setup:

  • The web entry must dynamically import the app so React refresh initializes before application chunks. Static imports can work on first load and fail after a route split.
  • Bundled dev rebuilds Tailwind through watched files. Its ordinary Vite hot-update hook expects a server/module graph that Rolldown does not provide.

The workarounds live in the web entry and Tailwind plugin.

Checks

Run checks for the files and packages you changed:

vp test run <files>
vp lint <files>
vp run --filter <package> typecheck

Use vp run lint:mobile for native mobile changes. CI owns the full suite; see ci.yml for its current jobs. The manual Windows lane is available for focused Windows investigation while that suite is not a required gate.

Unused code

vp run knip:check checks unused files and dependencies across the repo, then unused exports and types in packages/tailscale and packages/effect-codex-app-server. CI enforces both checks. Use vp run knip --workspace apps/web to audit one workspace, including exports, or vp run knip:production --workspace apps/web to find code kept alive only by tests. The full export audit still has findings and is not a repo-wide CI gate. Extend the export check's workspace selectors as more workspaces become clean. Review callers before deleting code; production mode can also report development scripts and test fixtures. Runtime-discovered entrypoints and dependency exceptions belong in knip.jsonc.

Desktop artifacts

Local artifact builds are unsigned by default and write to release/:

vp run dist:desktop:dmg
vp run dist:desktop:linux
vp run dist:desktop:win

DMGs default to the host architecture. Use --arch to choose another target and --keep-stage to retain packaging files for inspection. Run vp run dist:desktop:artifact --help for other options.

Linux AppImage prerequisites

Build on Linux because the browser-secret helper links against the host's libsecret. Install Rust, C/C++ build tools, libsecret development headers, pkg-config, and ImageMagick.

Ubuntu and Debian:

sudo apt-get update
sudo apt-get install cargo rustc build-essential libsecret-1-dev pkg-config imagemagick

Fedora:

sudo dnf install rust cargo gcc gcc-c++ make libsecret-devel pkgconf-pkg-config ImageMagick

Arch Linux:

sudo pacman -S rust base-devel libsecret pkgconf imagemagick

The C toolchain, pkg-config, and libsecret headers are also needed for Linux desktop development.

macOS DMG prerequisites

Install the Xcode Command Line Tools with xcode-select --install and install Rust. For a cross-architecture or universal build, add the requested Rust targets:

rustup target add aarch64-apple-darwin x86_64-apple-darwin

Windows installer prerequisites

Install Rust, Python 3, and Visual Studio Build Tools with Desktop development with C++. Include the Windows SDK and the MSVC build tools and Spectre-mitigated libraries for the target architecture. Add its Rust target:

rustup target add x86_64-pc-windows-msvc
# For an ARM64 installer:
rustup target add aarch64-pc-windows-msvc

NSIS is downloaded by electron-builder. WSL support additionally needs a Linux node-pty prebuild; see the release runbook.

Signing and passkeys

Add --signed after configuring the platform credentials in the release runbook. macOS passkeys need a signed, provisioned app; follow the Connect setup for local signing and renderer HMR.