Contributing

Contributions are welcome. Please read the CONTRIBUTING.md and AGENTS.md in the repository for detailed guidelines.

Development workflow

git clone https://github.com/circle-rd/auth-service.git
cd auth-service
pnpm install
cp .env.example .env
# Edit .env: set BETTER_AUTH_SECRET, BETTER_AUTH_URL=http://localhost:3001 and ADMIN_* (pnpm dev does not expand ${...} references)
docker compose up -d postgres
pnpm db:migrate
pnpm dev

See the Quick start for the full from-source setup, including the admin frontend.

Running tests

Unit tests (no database required):

pnpm test

Integration tests start their own ephemeral PostgreSQL 17 container through testcontainers, so Docker must be running:

pnpm test:integration

The CI workflow runs pnpm build:server, pnpm lint, pnpm format:check, pnpm test and pnpm test:integration.

Code style

• TypeScript strict mode ("strict": true in tsconfig.json)
• ESM only ("type": "module" in package.json)
• No default exports from route files — all exports are named functions

Submitting changes

1. Create a branch from develop, the work branch (main is the production branch, see AGENTS.md).
2. Make your changes with appropriate test coverage.
3. Ensure pnpm build:server, pnpm lint, pnpm format:check, pnpm test and pnpm test:integration pass.
4. Open a pull request.