Skip to content

Onboarding — Jadu Auth repo

This doc walks you through setting up the repo and explains what you need to know along the way.

1. Clone and install

git clone <repo-url> jadu-auth
cd jadu-auth
npm install

Why a single npm install? This repo is an npm workspaces monorepo. The root package.json declares workspaces: fe, be, package, package/playground/fe, package/playground/be. One npm install at the root installs dependencies for all of them and hoists shared ones. Always run npm install from the repo root; you can still run workspace scripts from root with npm run <script> -w <workspace-name> or by cd-ing into a workspace.

2. What’s in the repo (high level)

Folder What it is Run / build
be/ Auth backend. Express server: signup, login, sessions, email OTP, SMS OTP (login only), password reset, RBAC, admin API. Uses MongoDB and Better Auth. From root: npm run dev:be. From be/: npm run dev.
package/ SDK @scenarix/jadu-auth. Consumed by apps for React auth (provider, hooks) and server-side JWT verification. From root: npm run dev:package (watch), npm run build:package.
fe/ Admin frontend (Next.js) for the auth service. From root: npm run dev:fe.
package/playground/ Example app: React frontend + Express API that use the SDK against the auth backend. Used for manual testing and demos. From root: npm run dev runs fe, be, package, playground fe, playground be together.
docs/ Repo-level documentation (this file, INFRA, CI/CD notes). —

The backend is the main service; the SDK is the library other apps depend on; fe and playground are applications that talk to the backend.

3. Backend: env and run

To run the backend (locally or as the target for the playground), you need a few env vars.

  1. Copy the example env file

From repo root:

cp be/.env.example be/.env

  1. Set required values in be/.env

  2. MONGODB_URI_JADU_AUTH — MongoDB connection string. For local dev you can use a local MongoDB or a free Atlas cluster.

  3. BETTER_AUTH_SECRET — A secret key (32+ characters). Never commit this. Generate one for local dev and use a different one in production.
  4. BETTER_AUTH_URL — Base URL of the auth server (e.g. http://localhost:8084 for local).
  5. TRUSTED_ORIGINS — Comma-separated allowed origins (e.g. http://localhost:3000,http://localhost:8083 for the playground and API).

Optional but useful: JADU_SPINE_JWT_SECRET if you use JaduSpine/Centrifugo tokens. For mail (verification, password reset) and SMS OTP login, see be/.env.example (SMTP_*, TWILIO_*, and SMS_PROVIDER).

  1. Run the backend

From repo root:

npm run dev:be

Or from be/:

npm run dev

Server: http://localhost:8084. API docs (Swagger): http://localhost:8084/api-docs.

4. Run the full stack (optional)

To run backend, SDK (watch), admin frontend, and playground fe + be together:

npm run dev

This uses concurrently to start all five. Useful to exercise the full flow (e.g. playground UI → auth backend).

Notes for SMS OTP login in playground:

  • SMS OTP is currently login-only (signup remains email-based).
  • For local testing, create the user first via email signup/login flow, then seed user.phone in MongoDB.
  • Set Twilio env vars in be/.env (TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_FROM_NUMBER) if you want real SMS delivery.

5. Backend tests and git hooks

  • Integration tests (Vitest, config-driven, run against an in-memory MongoDB):

From repo root:

npm run test:integration --workspace=jadu-auth-be

Or from be/:

npm run test:integration
  • Git hooks (Lefthook)
    When you push commits that touch be/, a pre-push hook runs: lint, build, and integration tests with coverage. To install the hooks (once per clone):
npm run setup

(Runs from root or from be/; config is in the root lefthook.yml.)

So: before your first push that changes be/, run npm run setup and fix any lint/build/test failures.

  • Backend structure and conventions — be/README.md (quick start, endpoints, layout) and be/CONVENTIONS.md (naming, request flow, patterns). If the team has added be/docs/, use that for architecture and contribution (adding routes, auth methods, tests).
  • SDK usage — Root README.md (entry points, API summary) and package/README.md (full SDK docs).
  • Deployments and infra — docs/INFRA.md (how backend, frontend, and SDK are deployed).

Quick checklist

  • [ ] Clone repo, run npm install at root.
  • [ ] Copy be/.env.example to be/.env and set MONGODB_URI_JADU_AUTH, BETTER_AUTH_SECRET, BETTER_AUTH_URL, TRUSTED_ORIGINS.
  • [ ] Run backend: npm run dev:be; open http://localhost:8084/api-docs.
  • [ ] Run integration tests: npm run test:integration --workspace=jadu-auth-be (or from be/).
  • [ ] Install git hooks: npm run setup.
  • [ ] Skim be/README.md and be/CONVENTIONS.md; read INFRA.md for deployment overview.