Documents › Contribution Guide
This file is contributor-facing: quick setup, how to opt in to local hooks, and a short PR checklist. For detailed developer instructions (environment, hooks internals, release process, CI parity, and troubleshooting) see the developer guide.
git clone https://github.com/cashubtc/cashu-ts.git
cd cashu-ts
# install exact deps used by CI
npm ci
# optional: prepare Playwright browsers for integration tests
npm run test:prepare
# optional: opt in to local git hooks
npm run setup-hooks
npm run compilenpm run lintnpm run formatnpm testnpm run api:update and commit /etc/cashu-ts.api.mdWe provide an optional hook installer. Run npm run setup-hooks to copy tracked hook sources from scripts/hooks/ into an ignored .githooks/ folder and activate them locally. Hooks are opt-in; CI still runs the full checks.
If you want the installer behavior or hook internals, see the Hooks section in DEVELOPER.md.
There is a convenience script npm run prtasks that runs the full PR/CI suite (lint, format, api:update, tests). The installed pre-push hook runs npm run prtasks to ensure the full checks before pushing. You may run it manually before opening a PR.
If you need the pre-commit hook to run the full suite for one commit, set FULL_PRECOMMIT=1 when committing:
FULL_PRECOMMIT=1 git commit -m "..."
Tip: a common local workflow before pushing is to run npm run prtasks and, for integration tests, start a local mint using the example docker-compose (see examples/auth_mint/docker-compose.yml) and then run npm run test-integration. This reproduces CI conditions locally and reduces surprises.
This project uses API-Extractor in CI. For details on npm run api:check and npm run api:update and the correct workflow for updating API reports, see DEVELOPER.md.
When adding new features that are subject to change, use the @experimental tag in TSDoc comments:
/**
* This function does something new and exciting.
*
* @experimental This API is subject to change.
*/
export function myNewFeature(): void {
// ...
}
Why @experimental instead of @alpha or @beta?
Our vite build process excludes @alpha and @beta tagged items from the public API. Using @experimental allows us to surface new features while clearly flagging them as subject to change.
Use // TODO: comments to mark areas needing future attention, such as deprecated code blocks or planned improvements:
// TODO: Remove this deprecated method in v4.0
export function oldMethod(): void {
// ...
}
This convention allows common editor plugins like Better Comments to highlight these areas for easy identification.
These tests expect a local mint at http://localhost:3338. Use the Make targets below to start one, you will need Docker installed locally, for example via Homebrew or Docker Desktop.
# CDK Mint
DEV=1 make cdk-up
# tear down
DEV=1 make cdk-down
# Nutshell
DEV=1 make nutshell-up
# tear down
DEV=1 make nutshell-down
To prevent accidental use, these targets require DEV=1 to be set, either by prefixing the command as shown above, or by exporting it in your shell:
export DEV=1
make cdk-up
make nutshell-up
On Apple Silicon the Makefile detects arm64 and runs the container with an amd64 image automatically, if you need to override, pass PLATFORM=linux/amd64 or PLATFORM=linux/arm64.
For a faster developer experience, these developer presets enable friendly defaults such as a permissive transaction rate limit and short fake wallet delays.
Then run the tests:
# full test suite
npm test
# integration only
npm run test-integration
*-down targets already do this for you.MINT_TRANSACTION_RATE_LIMIT_PER_MINUTE=100. The developer preset sets a higher limit by default.3338.lib/**/*.js) must have .js on relative imports.lib/**/*.cjs) may omit extensions, Node does not require them.lib/types/**/*.d.ts) are a rolled up file (no relative imports/re-exports).Thanks for contributing — please open Issues or Pull Requests if anything is unclear.