6.8 KiB
Contributing to SettleKit
Thanks for working on SettleKit. This guide covers how the monorepo is laid out, how to add a new package or app, and the conventions every contribution must follow.
Getting started
corepack enable
corepack prepare pnpm@11.3.0 --activate
pnpm install
pnpm build # tsc project references, builds packages + apps in order
pnpm typecheck # tsc -b across the workspace
You need Node 20+ and pnpm 11. See README.md for running individual apps and ARCHITECTURE.md for the system model.
Repo layout
packages/*— reusable domain libraries published as@settlekit/<name>.@settlekit/persistenceholds every Postgres store;@settlekit/databasethe drizzle schema, migrations, and doc codec.apps/*— deployable apps (api,worker,cli, and the Next.js frontends).sdks/*— first-party SDKs in TypeScript (packages/sdk), Python, Go, Rust.clis/*— standalone CLIs (e.g. the Goagentpayx402 agent client).services/*— edge services in Rust/Go (arc-indexer, x402-gateway, license-gateway, webhook-relay).examples/*— runnable integration examples (Python SaaS, Express x402, Go paid client, Rust license check, Next.js SaaS starter).tsconfig.base.json— shared compiler options (NodeNext, strict,verbatimModuleSyntax,noUncheckedIndexedAccess).- The pnpm workspace covers
packages/*+apps/*only;sdks/,clis/,services/, andexamples/are self-contained (their own toolchains) so they never affectpnpm -r build.
Adding an API endpoint (keep clients in sync)
A new /v1 endpoint isn't done until the clients can call it. After adding the
route (apps/api/src/routes/*.ts + mount in app.ts + any context wiring):
- TS SDK (
packages/sdk): add/extend a resource insrc/resources/, register it insrc/client.ts, and export it fromsrc/index.ts. - Python / Go / Rust SDKs (
sdks/*): add the matching method (Python: sync + async classes; Go: a*Clientmethod; Rust: a resource accessor). - If it's a list endpoint backing a dashboard page, thread the listing method through the interface → in-memory → Postgres store, not just the route.
Conventions
TypeScript + ESM (required)
The repo is ESM with module: NodeNext and verbatimModuleSyntax: true. That
imposes three hard rules:
-
Relative imports end in
.js— you import the compiled output, even from a.tssource file:import { buildDeliveryPlan } from "./delivery-plan.js"; -
Workspace imports use the package name with no suffix:
import { money, type Entitlement } from "@settlekit/common"; -
Type-only imports use
import type(or inlinetype), required byverbatimModuleSyntax:import type { Payment, DeliveryRun } from "@settlekit/common";
noUncheckedIndexedAccess is on, so indexed access yields T | undefined —
handle the undefined case explicitly. Do not use non-null assertions to silence
it.
Immutability
Never mutate inputs. Build and return new objects:
// Wrong: mutates the caller's object
function activate(e: Entitlement) { e.status = "active"; return e; }
// Right: returns a new value
function activate(e: Entitlement): Entitlement {
return { ...e, status: "active" };
}
The @settlekit/common contract
@settlekit/common is the foundation every other package builds on. It is the
single source of truth for:
- Domain types —
Product,Price,Bundle,Customer,CheckoutSession,Payment,Subscription,Entitlement,EntitlementType,LicenseKey,ApiKey,DeliveryRun,WebhookEndpoint,AgentService,EscrowTask,MarketplaceListing. - Money — the
Moneytype and themoney()constructor. Never represent amounts as rawnumber; usemoney(). - Result handling —
Result,ok,err,isOk,isErr. Domain functions returnResultinstead of throwing for expected failures. - Errors —
SettleKitErrorfor exceptional failures. - Ids —
generateIdfor all entity ids.
Rules:
- Put a shared domain type in
@settlekit/common, not in a feature package. @settlekit/commondepends on nothing else in the workspace.- Prefer
Result/ok/errover throwing for recoverable, expected outcomes; reserveSettleKitErrorfor true exceptions.
Code style
- Small, focused files (200–400 lines typical). Organize by feature/domain.
- Validate at boundaries (HTTP handlers, external API responses) with Zod.
- API responses use the
{ data }/{ error }envelope — no bare payloads. - Handle errors explicitly; never swallow them silently.
Adding a new package
-
Create
packages/<name>/withsrc/and atsconfig.jsonthat extends the base and iscomposite:// packages/<name>/tsconfig.json { "extends": "../../tsconfig.base.json", "compilerOptions": { "rootDir": "./src", "outDir": "./dist", "composite": true }, "references": [{ "path": "../common" }], "include": ["src/**/*"], "exclude": ["dist", "node_modules"] } -
Add
packages/<name>/package.jsonnamed@settlekit/<name>,type: module, withmain/typespointing at./dist/index.js/./dist/index.d.ts, abuildscript oftsc -b, andworkspace:*deps on the packages you use. -
Add a
referencesentry for../<name>to the roottsconfig.json(and to any package/app that imports it) so project-reference builds stay correct. -
Run
pnpm installto link the workspace, thenpnpm build.
Keep the dependency graph pointing downward (see ARCHITECTURE.md §3): feature packages depend on
commonand lower-level packages, never on apps.
Adding a new app
-
Create
apps/<name>/with apackage.jsonnamed@settlekit/<name>.- Node app (like
api/worker):build: "tsc -b", astartthat runsnode dist/..., and acompositetsconfig.jsonlisting its packagereferences. Add a multi-stageDockerfilemodeled onapps/api/Dockerfileand a service indocker-compose.yml. - Next app:
dev/build/startusingnext, withstarthonouring-p $PORT. Reuse the sharedDockerfile.nextby adding a service withAPP_DIR,APP_PKG, andAPP_PORTbuild args, and assign a unique host port.
- Node app (like
-
Wire the app into
docker-compose.ymland, if it needs the database, add adepends_on: postgreswithcondition: service_healthy.
Submitting changes
- Keep commits focused; use conventional commit messages
(
feat:,fix:,refactor:,docs:,chore:,perf:,ci:). - Before opening a PR, ensure
pnpm install --frozen-lockfile,pnpm -r build, andpnpm typecheckall pass locally. - Don't commit secrets or a real
.env.