Contributing

Vault is open source and welcomes contributions. This guide covers development setup, coding standards, and the contribution workflow.

Getting Started

Prerequisites

Node.js 20+
pnpm 9+
Git

Clone & Install

# Clone the repository
git clone https://github.com/zeroexcore/vault.git
cd vault
 
# Install dependencies
pnpm install
 
# Start development servers
pnpm dev

This starts:

Web app at http://localhost:5175
API at http://localhost:8787

Mock Mode

For UI development without real authentication:

pnpm dev:mock

This bypasses WebAuthn and uses mock data.

Development Workflow

1. Pick an Issue

Browse Linear issues or GitHub issues.

2. Create Branch

# Fetch latest
git f
git checkout main
git rebase origin/main
 
# Create feature branch
git checkout -b feature/OXC-123-description origin/main

3. Make Changes

Write code following coding standards
Add tests for new functionality
Run typecheck: pnpm typecheck

4. Commit

git add .
git commit -m "feat(OXC-123): add password strength meter"

5. Push & Create PR

git push -u origin feature/OXC-123-description
gh pr create --title "feat(OXC-123): add password strength meter"

Coding Standards

TypeScript

Strict mode enabled
Explicit return types for exported functions
Use interface over type for objects
No any — use unknown if needed

Formatting

2 spaces indentation
Single quotes for strings
No semicolons (configured in Prettier)
Max line length: 100

Naming

Type	Convention	Example
Files	kebab-case	`password-generator.ts`
Components	PascalCase	`PasswordGenerator.tsx`
Functions	camelCase	`generatePassword()`
Constants	SCREAMING_SNAKE	`MAX_PASSWORD_LENGTH`

Imports

// External packages first
import { useState } from "react";
import { z } from "zod";
 
// Internal packages (@pwm/*)
import { generatePassword } from "@pwm/shared";
 
// Relative imports last
import { Button } from "./Button";

Project Structure

packages/
├── api/          # Hono API on Cloudflare Workers
├── web/          # React frontend
├── cli/          # Node.js CLI
├── mobile/       # React Native (Expo)
├── shared/       # Shared utilities
├── cdn/          # Static assets
└── docs/         # Documentation (you are here)

See Project Structure for details.

Testing

Unit Tests

# Run all tests
pnpm test
 
# Run specific package
pnpm --filter @pwm/shared test
 
# Watch mode
pnpm --filter @pwm/shared test:watch

E2E Tests

# Web (Playwright)
pnpm --filter @pwm/web test:e2e
 
# Mobile (Detox) - requires iOS/Android setup
cd packages/mobile
pnpm test:e2e:ios

See Testing Guide for details.

Pull Request Guidelines

PR Title

Format: type(scope): description

feat(OXC-123): add password strength indicator
fix(OXC-456): resolve login timeout
docs: update CLI documentation

PR Description

## Summary
 
Brief description of changes.
 
## Linear Issue
 
Closes OXC-123
 
## Changes
 
- Change 1
- Change 2
 
## Screenshots (for UI changes)
 
![Screenshot](url)
 
## Testing
 
- [ ] Unit tests pass
- [ ] Typecheck passes
- [ ] Manual testing completed

Review Process

Open PR
CI runs (lint, typecheck, tests)
Code review
Address feedback
Merge when approved

Branch Strategy

Branch	Purpose
`main`	Development, deploys to staging
`production`	Production releases
`feature/*`	Feature development
`bugfix/*`	Bug fixes

Code Review

What We Look For

Correctness: Does it work?
Security: No vulnerabilities introduced?
Performance: Efficient implementation?
Readability: Easy to understand?
Tests: Adequate coverage?

Response Time

We aim to review PRs within 48 hours.

Getting Help

Questions: Open a GitHub Discussion
Bugs: Open a GitHub Issue
Security: Email security@oxc.dev

License

Vault is open source under the MIT License.