integrate-holeauth

Integrate holeauth

Dispatcher skill. Interviews the user, then loads the appropriate per-package integration skills in dependency order.

When NOT to use

• Starting a brand-new Next.js project from scratch → use bootstrap-nextjs-holeauth instead.
• Building a custom holeauth plugin → use holeauth-plugin-design.

Source of truth

Implementation details live in the docs. Fetch them on demand:

• Docs root: https://docs.holeauth.dev/docs
• Search API: GET https://docs.holeauth.dev/api/search?q=<term>
• Reference auth setup: apps/playground/lib/auth.ts in the holeauth repo.

Procedure

Step 1 — Interview

Use vscode_askQuestions with these questions. Never assume defaults — always ask.

Step 2 — Route to per-package skills

Run skills in this strict order. Each loaded skill inherits the answers from Step 1.

1. Always: integrate-holeauth-core
2. If plugins includes 2FA: integrate-holeauth-2fa
3. If plugins includes Passkeys: integrate-holeauth-passkey
4. If plugins includes RBAC: integrate-holeauth-rbac
5. If plugins includes IDP server: integrate-holeauth-idp
6. If plugins includes IDP consumer: integrate-holeauth-idp-consumer
7. If trpc === Yes: integrate-holeauth-trpc

If framework is Express or Hono: do NOT bail. The integrate-holeauth-core skill supports these frameworks. Pass the framework variable through and the core skill will reference the correct platform adapter and docs.

Step 3 — Superuser bootstrap

Based on the superuser choice, write the corresponding artifact:

• Seed script → scripts/seed.ts with a tsx shebang that creates the first user and assigns the admin group (only valid if RBAC was selected).
• Bootstrap CLI → scripts/bootstrap-admin.ts that reads CLI args / prompts for email + password.
• Env-driven → scripts/promote-from-env.ts reading BOOTSTRAP_ADMIN_EMAIL on first boot.
• Manual SQL → emit a docs/SUPERUSER.md with the exact SQL.
• None → skip.

Step 4 — Verification checklist

Print this checklist back to the user. They run the commands; you don't.

[ ] pnpm install completed without peer-dep warnings
[ ] Drizzle migration generated and applied (pnpm db:push or drizzle-kit push)
[ ] Auth route handler responds at <basePath>/... (e.g. GET /api/auth/.well-known/openid-configuration)
[ ] Middleware is in place and protects authenticated routes
[ ] HoleauthProvider wraps the app in the root layout
[ ] /login page exists and loads (200 — no 404)
[ ] /register page exists and loads (if registration is self-serve or both)
[ ] /(guest)/layout.tsx (or equivalent) redirects authenticated users away from guest routes
[ ] Sign-up flow completes end-to-end
[ ] Sign-in flow completes end-to-end
[ ] If 2FA selected: /2fa/verify page exists; TOTP code accepted after sign-in
[ ] If Passkeys selected: passkey register and login pages exist and work
[ ] If RBAC selected: default group auto-assigned after registration
[ ] Font set in root layout (not browser default serif)
[ ] Superuser created (if applicable)
[ ] Required env vars set: HOLEAUTH_SECRET, DATABASE_URL, APP_URL
[ ] pnpm typecheck passes
[ ] pnpm build succeeds

Hard constraints

• Never invent options. If unsure, ask. Never write defineHoleauth directly in Next.js setups — use createAuthHandler from @holeauth/nextjs-app-router.
• Plugin factory names: twofa, passkey, rbac, idp. Adapter factories: createHoleauthAdapters, createRbacAdapter, createTwoFactorAdapter, createPasskeyAdapter, createIdpAdapter — all take { db, tables }.
• Plugins array must be as const for full TypeScript inference of auth.<pluginKey>.<method>().
• cookiePrefix must be identical in createAuthHandler, holeauthMiddleware, and HoleauthProvider.

Need more detail?

GET https://docs.holeauth.dev/api/search?q=<topic>

Example queries: account linking, audit log, refresh rotation, csrf, events.