Contributing and development

Run the app and static website, then verify changes before contributing.

Set up the repository

Use Node 24.19.0 from .node-version and pnpm 10.28.2. Source builds require Node 24.15.0 or later. Clone the repository with your GitHub access, then install from the root. Keep API keys and signing credentials outside source control.

pnpm install
pnpm dev

Verify a change

Run type checking, lint, security checks, and tests before sharing app changes. Limit Vitest to two fork workers on memory-constrained machines. Live provider checks require explicit opt-in and authentication. A skipped live check does not prove provider operation.

pnpm typecheck
pnpm lint
pnpm test --pool=forks --maxWorkers=2
pnpm security:static
pnpm knip

Build the website

The @vstudy/website package uses Astro static output. It makes no analytics or third-party font requests. Download assets and detection come from src/data/downloads.ts. Source version metadata comes from src/config.ts and is not a verified installer version. Docs routes and search share the same typed content registry.

BASE_PATH defaults to /vstudy-pro for GitHub Pages. Set BASE_PATH=/ for root hosting. SITE_URL controls the canonical origin. The Pages workflow builds and uploads only static output. It does not publish desktop releases.

pnpm --filter @vstudy/website build
pnpm --filter @vstudy/website preview

Make a focused contribution

Keep main, renderer, and shared ownership separate. Put app strings in the matching English, Traditional Chinese, and Japanese namespaces. Update the website’s locale dictionaries for website copy.

Use small Conventional Commits with a description of why the change is needed. Include current evidence for behavior or UI changes. Never commit credentials, real student data, or generated release artifacts.

Source reference