Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
119 lines (83 loc) · 3.19 KB

CONTRIBUTING.md

File metadata and controls

119 lines (83 loc) · 3.19 KB

Contributing to PayKit

Thanks for your interest in contributing! This guide will help you get set up and explain how we work.

For questions or ideas, open a GitHub issue before starting large work.

Prerequisites

  • Node.js >= 22
  • bun (install via bun.sh)

Local Setup

# Fork then clone
git clone https://github.com/<your-username>/paykit.git
cd paykit

bun install
bun build

Development

bun dev           # Watch mode (Turbo)
bun typecheck     # tsc --build
bun lint          # oxlint --deny-warnings
bun lint:fix      # Auto-fix lint issues
bun format        # oxfmt
bun format:check  # Check formatting without writing

Monorepo Structure

packages/
  paykit/       # Core orchestration package
  stripe/       # Stripe provider
  dash/         # Dashboard
  polar/  # Polar provider
apps/
  demo/         # Demo app
  web/          # Next.js web app
e2e/            # End-to-end tests

Testing

We use Vitest. Run a specific test file or pattern:

vitest /path/to/test-file -t "pattern"
  • Bug fixes and new features must include tests.
  • For regression tests, add a @see JSDoc comment with the issue URL:
/** @see https://github.com/getpaykit/paykit/issues/123 */
it("does not throw when ...", () => {

Code Style

Enforced by oxlint and oxfmt (not Prettier or Biome; do not add them). For a deeper reference on conventions and tooling, see AGENTS.md.

Key rules:

  • TypeScript strict mode; no any, no @ts-ignore (use @ts-expect-error with an explanation)
  • import type for type-only imports, separated from value imports
  • import * as z from "zod", never import { z } from "zod"
  • No enums; use as const objects or union types
  • No classes; use plain functions and objects
  • Node.js built-ins use the node: protocol (node:fs, node:path)
  • No Buffer in library code; use Uint8Array

Commits & Pull Requests

We follow Conventional Commits:

feat(stripe): add webhook handler
fix(paykit): correct subscription renewal logic
docs: update README setup steps
chore: bump bun to 1.3.13

The scope is the package name (paykit, stripe, dash, polar).

  • PRs target main
  • For bug fixes or non-breaking improvements, a PR is enough
  • For new features or breaking changes, open an issue first to discuss

Changesets

When you change anything under packages/, run:

bun changeset

Follow the prompts to describe the change. Commit the generated .changeset/*.md file with your PR.

Reporting Bugs

Search existing issues first. If none match, open a new one with:

  • A minimal reproduction
  • Expected vs. actual behavior
  • Node.js version and relevant package versions

Security

Do not open a public issue for security vulnerabilities. Email security@paykit.sh instead.

AI-Assisted Contributions

AI-assisted PRs are welcome. The bar is the same as for any other PR: the change solves a real problem, includes tests, and the contributor can speak to the code in review.