Development Workflow & Scripts

Relevant source files

The following files were used as context for generating this wiki page:

• package.json
• CLAUDE.md
• vite.config.ts
• scripts/setup-gh-project.sh
• vitest.config.ts
• README.md

The Vata project utilizes a structured development workflow centered around the pnpm package manager, the Tauri 2 desktop framework, and strict engineering standards. This workflow encompasses local development, automated testing, code quality enforcement, and GitHub project orchestration to maintain a high-velocity, localized development environment.

The project is built on a tech stack featuring React 18, TypeScript, and Vite for the frontend, with a Rust-based Tauri shell providing access to the native operating system and SQLite databases. Development is governed by explicit guidelines regarding English-only documentation, specific git branching strategies, and automated linting and formatting.

Sources: README.md:27-36, CLAUDE.md:46-51, CLAUDE.md:144-156

Core Development Scripts

The project defines a comprehensive set of scripts in package.json to handle the lifecycle of the application, from initial development to production builds and testing.

Command	Description	Component
pnpm dev	Starts the Vite development server (port 1420)	Frontend
pnpm tauri:dev	Launches the full Tauri desktop app in development mode	Full Stack
pnpm build	Executes TypeScript checks and Vite production build	Frontend
pnpm tauri:build	Builds the distributable native desktop application	Full Stack
pnpm test	Runs Vitest in watch mode	Testing
pnpm test:coverage	Generates a V8 coverage report	Testing
pnpm lint	Checks code against ESLint rules	Quality
pnpm format	Rewrites files using Prettier	Quality
pnpm verify	Executes lint, format check, build, and tests sequentially	CI/CD

Sources: package.json:37-51, CLAUDE.md:13-26

Local Development Flow

The preferred method for development is pnpm tauri:dev, which orchestrates both the frontend Vite server and the Rust backend.

The diagram shows how the development command initializes the internal server and native shell to provide a live-reloading environment.
Sources: CLAUDE.md:15-16, src-tauri/tauri.conf.json:8-13

Git & Branching Strategy

Vata follows a strict "No direct commits to main" policy. Every change must be submitted via a Pull Request (PR) after passing a specific local review process.

Branch Modes

The project distinguishes between two working modes based on the complexity of the task:

• Simple Branch: Used for trivial fixes or single-file documentation changes.
• Worktree Mode: Recommended for multi-file changes, new features, or refactors. Developers are instructed to use the EnterWorktree tool rather than raw git commands to ensure proper session registration.

Branch Naming Conventions

Branches must follow conventional prefixes:

• feat/: New features
• fix/: Bug fixes
• docs/: Documentation updates
• refactor/: Code restructuring
• test/: Test additions only

Sources: CLAUDE.md:167-210

Pre-PR Verification

Before a PR is created, developers must execute a three-step verification:

1. Simplify: Run /simplify to launch agent-based quality reviews.
2. Review: Run /review locally to address findings.
3. Verify Script: Execute pnpm verify to ensure linting, formatting, and tests pass.

Sources: CLAUDE.md:231-238, package.json:49

Infrastructure & Project Setup

The repository includes automation for bootstrapping the GitHub environment to match the project's taxonomy.

GitHub Project Orchestration

The scripts/setup-gh-project.sh script automates the creation of labels and project structures. It ensures that specific "Genealogy data domains" labels exist and deletes deprecated ones.

The flow represents the idempotent setup process for the project's GitHub management environment.
Sources: scripts/setup-gh-project.sh:14-118

Build Configuration

The project uses vite.config.ts and vitest.config.ts to manage path aliases and build targets. Aliases are synchronized between development and testing environments to ensure consistency.

Key Path Aliases:

• $/*: src/*
• $db-tree/*: src/db/trees/*
• $managers/*: src/managers/*
• @vata-apps/gedcom-parser: src/gedcom-parser

Sources: vite.config.ts:25-39, vitest.config.ts:14-25, CLAUDE.md:105-121

Testing Standards

Testing is performed using Vitest with jsdom. Tests are co-located with their source files (e.g., src/db/trees/individuals.test.ts).

Database Unit Testing

For database layer tests, the project utilizes an in-memory SQLite helper (src/test/sqlite-memory.ts) to avoid side effects on the local system.db or tree databases.

The sequence shows how the database layer is isolated during unit tests to ensure speed and reliability.
Sources: CLAUDE.md:133-140, src/db/trees/files.test.ts:16-25

Summary

The Vata development workflow is designed for a local-first application, emphasizing rigorous pre-commit checks and automated environment setup. By integrating Tauri-specific scripts with standard React/TypeScript tooling and custom GitHub orchestration, the project maintains a consistent development lifecycle across various operating systems.

Sources: README.md:103-111, CLAUDE.md:21-42