Repository Guidelines

Project Structure & Module Organization

src/index.ts is the Worker entrypoint for HTTP routes, asset delivery, scheduled cleanup, and queue handling. Core domain logic lives in src/lib/ (config.ts, model.ts, repository.ts, schema.ts, types.ts). Static SPA assets are served from assets/, one-off import tooling lives in scripts/, D1 schema changes live in migrations/, and Worker integration tests live in test/. GitHub Actions workflows are in .github/workflows/.

Build, Test, and Development Commands

Install dependencies with bun install.

bun run dev or bun run start: run the Worker locally with Wrangler.
bun run check: run TypeScript type-checking without emitting files.
bun run test: run Vitest in the Cloudflare Workers test pool.
bun run test:coverage: run tests with Istanbul coverage output in coverage/.
bun run format / bun run format:check: apply or verify Prettier formatting.
bun run cf-typegen: refresh Worker binding types after Wrangler config changes.
bun run deploy: publish the Worker.
bun run import:privatebin:fs -- --source <dir> --base-url <url> --token <token>: import a PrivateBin filesystem export.

Coding Style & Naming Conventions

TypeScript uses tabs, LF line endings, UTF-8, semicolons, single quotes, and a printWidth of 140. Follow the existing pattern of small helpers with clear names such as handleCreatePaste, resolveConfig, and buildPasteBlobKey. Use PascalCase for classes, camelCase for functions and variables, and keep route, storage, and validation logic separated.

Testing Guidelines

Vitest covers src/**/*.ts; .d.ts, scripts/, migrations/, and tests are excluded from coverage. Codecov targets 95% project coverage and 90% patch coverage, so new changes should include or update tests. Add specs under test/ with the *.spec.ts suffix and prefer descriptive names grouped by feature, for example repository.spec.ts or http-errors.spec.ts.

Commit & Pull Request Guidelines

Use Conventional Commits for commit messages, for example feat: improve homepage SEO messaging or fix: avoid skipping required CI workflow. Keep each commit focused on one change, use the smallest accurate type (feat, fix, docs, refactor, test, chore, etc.), and add a scope when it clarifies the affected area, such as feat(repository): support blob metadata lookup. For pull requests, include a concise summary, linked issues when applicable, test evidence (bun run test:coverage, bun run check, bun run format:check), and screenshots for assets/ UI changes.

Security & Configuration Tips

Start from .dev.vars.example for local secrets. Do not commit real Cloudflare credentials, import tokens, or .dev.vars contents. If you change bindings or environment variables, update wrangler.jsonc, regenerate types with bun run cf-typegen, and verify CI still passes.

2.9 KiB Raw Blame History