Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
172 lines (113 loc) · 5.67 KB

CONTRIBUTING.md

File metadata and controls

172 lines (113 loc) · 5.67 KB

Contributing Guide

Initial Setup

macOS / Linux

You'll need the following tools installed on your system:

brew install pnpm node just cmake

Install Rust & Cargo using rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
cargo install cargo-binstall

Initial setup to install dependencies for Vite+:

just init

Windows

You'll need the following tools installed on your system. You can use winget.

winget install pnpm.pnpm OpenJS.NodeJS.LTS Casey.Just Kitware.CMake

Install Rust & Cargo from rustup.rs, then install cargo-binstall:

cargo install cargo-binstall

Initial setup to install dependencies for Vite+:

just init

Note: Run commands in PowerShell or Windows Terminal. Some commands may require elevated permissions.

Build Vite+ and upstream dependencies

To create a release build of Vite+ and all upstream dependencies, run:

just build

Install the Vite+ Global CLI from source code

pnpm bootstrap-cli
vp --version

This builds all packages, compiles the Rust vp binary, and installs the CLI to ~/.vite-plus.

Validate the local build against a real project

Unit and snap tests don't cover everything. Interactive flows in particular (prompts, pickers, scaffolding) are easiest to validate by running your work-in-progress CLI inside a real Vite+ project.

First, understand how vp picks which vite-plus to run: for JS-backed commands (such as vp create), the global vp binary resolves vite-plus from the project's node_modules first and only falls back to the global installation in ~/.vite-plus. If your test project has vite-plus installed from npm, pnpm bootstrap-cli alone will not make it run your local code.

Build the local CLI package after each change:

pnpm -F vite-plus build      # TypeScript + native NAPI binding
pnpm -F vite-plus build-ts   # faster, when only TypeScript changed

pnpm link the local package

Link your checkout into the test project. The global vp then delegates to the project-local CLI, and re-entrant vp sub-commands (for example vp create running vp install and vp fmt after scaffolding) resolve back to the same linked checkout:

cd /path/to/test-project
pnpm link /path/to/vite-plus/packages/cli

vp create   # now runs your local checkout

Verify the link with ls -l node_modules/vite-plus (it should be a symlink into your checkout). Notes:

  • pnpm records the link as a vite-plus: link:... override (in pnpm-workspace.yaml for workspace projects, otherwise under pnpm.overrides in package.json), so it survives later installs. Don't commit that override in the test project.
  • pnpm link may also add a packageManager field to the test project's package.json; revert it if unwanted.
  • Undo with pnpm unlink vite-plus, or remove the override and run pnpm install.

Global CLI (Rust) changes

pnpm link only swaps the JS side; the vp binary on PATH (and the Rust-backed commands it handles directly, such as package-manager commands) is still whatever is installed in ~/.vite-plus. For changes to the Rust global CLI (crates/), install it from source, and combine with pnpm link when the change spans both layers:

pnpm bootstrap-cli
vp --version

Workflow for build and test

You can run this command to build, test and check if there are any snapshot changes:

pnpm bootstrap-cli && pnpm test && git status

Running Snap Tests

Snap tests verify CLI output. They are located in packages/cli/snap-tests/ (local CLI) and packages/cli/snap-tests-global/ (global CLI).

# Run all snap tests (local + global)
pnpm -F vite-plus snap-test

# Run only local CLI snap tests
pnpm -F vite-plus snap-test-local
pnpm -F vite-plus snap-test-local <name-filter>

# Run only global CLI snap tests
pnpm -F vite-plus snap-test-global
pnpm -F vite-plus snap-test-global <name-filter>

Snap tests auto-generate snap.txt files. Check git diff to verify output changes are correct.

Verified Commits

All commits in PR branches should be GitHub-verified so reviewers can confirm commit authenticity.

Set up local commit signing and GitHub verification first:

After setup, re-sign any existing commits in your branch so the full branch is verified:

# Re-sign each commit on your branch (replace origin/main with your branch base if needed)
git rebase -i origin/main
# At each stop:
git commit --amend --date=now --no-edit -S
# Then continue:
git rebase --continue

When done, force-push the updated branch history:

git push --force-with-lease

Pull upstream dependencies

Note

Upstream dependencies only need to be updated when an "upgrade upstream dependencies" pull request is merged.

To sync the latest upstream dependencies such as Rolldown and Vite, run:

pnpm tool sync-remote
just build

macOS Performance Tip

If you are using macOS, add your terminal app (Ghostty, iTerm2, Terminal, …) to the approved "Developer Tools" apps in the Privacy panel of System Settings and restart your terminal app. Your Rust builds will be about ~30% faster.