Skip to content

development.md

Latest commit

 

History

History
84 lines (62 loc) · 5.16 KB

development.md

File metadata and controls

84 lines (62 loc) · 5.16 KB
Raw

Development and Debugging

Environment Setup

Install Node.js, npm, the latest stable Rust toolchain, and the Tauri 2 dependencies for your platform. Then install project dependencies:

npm install

Ubuntu needs the Linux WebKitGTK/AppIndicator toolchain before npm run dev:app, npm run check, or npm run build:app:

sudo apt update
sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file libxdo-dev libssl-dev libappindicator3-dev librsvg2-dev patchelf xdg-utils

Dependency versions are locked by the root package-lock.json and apps/desktop/src-tauri/Cargo.lock. Include both lockfile changes whenever a dependency update is intentional.

Common Commands

Command Purpose
npm run dev Start the desktop browser preview with data from apps/desktop/src/demo.ts
npm run dev:app Start the complete Tauri desktop application
npm run dev:admin Start the admin console
npm run dev:backend Start the NestJS backend in watch mode
npm run build Build all npm workspaces through Lerna/Nx
npm run build:desktop Type-check and build the desktop frontend
npm run build:admin Build the admin console
npm run build:backend Build the NestJS backend
npm run build:app Build desktop installers
npm run build:app:mac Build a universal macOS bundle
npm run build:app:win-arm64 Build a Windows ARM64 bundle
npm run check:rust Check Rust formatting and run Rust tests
npm run check Run all pre-submission workspace checks plus Rust checks
npm run nx -- graph Open the Nx project graph
npm run release Bump the patch version, tag, and push a stable release
npm run release-beta Bump or create a beta prerelease tag

Browser Preview and Desktop Mode

The browser preview does not read real files, start OAuth, or access real accounts. apps/desktop/src/api/backend.ts selects the appropriate implementation by detecting the Tauri runtime. When adding a backend operation, also define its preview behavior: provide a demo result or clearly report that the operation is unavailable.

Use a custom Codex directory in desktop mode to avoid changing your everyday environment:

$env:CODEX_HOME = "$PWD\.local-codex"
npm run dev:app

The .local-codex/ directory may contain credentials. Confirm that it cannot be committed before using it. A temporary directory outside the workspace is safer.

For local Windows ARM64 app builds, install the Rust aarch64-pc-windows-msvc target and use a Visual Studio/MSVC developer environment with ARM64 build tools before running npm run build:app:win-arm64.

Debugging Guidelines

  • UI or state issue: reproduce it first with npm run dev and demo data.
  • IPC issue: verify that command names and arguments in apps/desktop/src/api/backend.ts match commands.rs.
  • File issue: set a temporary CODEX_HOME instead of modifying an account you regularly use.
  • OAuth issue: confirm that local ports 1455 and 1457 are free, then try the system-browser flow.
  • Tray issue: confirm system_tray::refresh_menu is called after account, usage, or active-account changes.
  • Floating bubble issue: inspect settings.json, window label usage-bubble, and the theme-color-changed event path.
  • Restart issue: test with a disposable Codex session. Windows uses taskkill; macOS and Linux use pkill plus the available relaunch strategy.
  • Rust logic: prefer unit tests around the pure parsing functions in auth.rs and codex_api.rs.

Release Workflow

npm run release and npm run release-beta require a clean working tree. The script updates package.json, package-lock.json, apps/desktop/package.json, and apps/desktop/src-tauri/tauri.conf.json, including a numeric WiX/MSI version derived from prerelease tags such as 0.2.3-beta.0 -> 0.2.3.0. It commits the version bump when needed, creates an annotated tag, then pushes both the current branch and tag to origin.

The GitHub Actions release workflow starts from v* tags or a manual run with an existing tag. It creates or finds the GitHub Release, generates release notes when needed, runs npm run check in each build job, and uploads Windows x64, Windows ARM64, Ubuntu/Linux x64, and macOS Apple Silicon and Intel artifacts.

Adding a Feature

  1. Define the smallest redacted transfer model in models.rs.
  2. Put external API, storage, or identity logic in the corresponding Rust module.
  3. Orchestrate the use case in commands.rs and register the command in lib.rs.
  4. Add a typed wrapper to apps/desktop/src/api/backend.ts.
  5. If the feature is app-level configuration, update AppSettings, storage.rs, and the browser-preview behavior in apps/desktop/src/api/backend.ts.
  6. If the feature affects tray or floating-bubble behavior, update system_tray.rs, floating_bubble.rs, and any relevant event refresh paths.
  7. Manage business state in a hook, then render it through pages and components.
  8. Update the relevant architecture or usage documentation and run npm run check.

Pages must not call invoke directly. Tauri command functions must not absorb JWT parsing, HTTP response parsing, or low-level file-replacement logic.