Dubs Auth Integration Skill

Guide for implementing @wiseiodev/dubs-auth cleanly in consumer applications.

When To Use

• User asks to set up dubs-auth, Better Auth + Stripe + Drizzle, or Next.js auth/billing routes.
• User asks how to use package exports like createDubsAuth, createBillingRouteHandlers, createDubsAuthClient, or subscription helpers.
• User needs troubleshooting for webhook sync, billing portal redirects, or env wiring.

When Not To Use

• Maintaining this library's internal release/build/test workflows.
• Non-Next.js stacks that do not use App Router style route handlers.

Workflow (Follow In Order)

1. Discover app context first.
   • Detect package manager, Next.js App Router presence, DB adapter usage, and whether auth/billing routes already exist.
   • Reuse existing app conventions before suggesting new structure.
2. Plan the smallest vertical slice.
   • Install package.
   • Scaffold with CLI (init, generate schema) when useful.
   • Wire env + createDubsAuth + /api/auth/[...all].
3. Add billing flow.
   • Wire /api/billing/portal and /api/stripe/webhook.
   • Resolve Stripe customer ID from current identity.
4. Add subscription persistence.
   • Normalize Stripe events with toDubsSubscriptionEvent.
   • Build patch via deriveSubscriptionPatchFromEvent.
   • Apply idempotent upsert via upsertSubscriptionRecord.
5. Provide concrete verification.
   • Include exact commands and route checks.
   • Include expected success/failure signals.
   • Prefer the examples/next-app-router flow as the default verification baseline.

Response Rules

• Best-practice-first guidance: production-safe defaults, explicit error handling, and idempotent webhook processing.
• Keep guidance grounded in real package exports and templates. Do not invent APIs.
• Prefer complete copy-paste snippets tied to concrete file locations.
• Always end with targeted validation commands and quick rollback/debug steps.

Verification Baseline (Use This First)

pnpm --dir examples/next-app-router install
pnpm --dir examples/next-app-router exec dubs-auth generate schema --cwd .
cp examples/next-app-router/.env.example examples/next-app-router/.env
pnpm --dir examples/next-app-router db:migrate
PORT=4000 pnpm --dir examples/next-app-router dev

Validate in order:

1. /sign-up can create an account.
2. /sign-in can authenticate that account.
3. /dashboard shows sessioned state.
4. /billing works for signed-in users.

Expected Stripe-optional behavior:

• If Stripe env vars are unset, billing portal/webhook routes should return a clear "not configured" response instead of crashing the app.

Troubleshooting Quick Fixes

If local PGlite files are unstable, reset and remigrate:

pnpm --dir examples/next-app-router exec node --input-type=module -e "import { rm } from 'node:fs/promises'; await rm('.data/dubs-auth', { recursive: true, force: true }); await rm('.data/dubs-auth-wal', { force: true }); await rm('.data/dubs-auth-shm', { force: true });"
pnpm --dir examples/next-app-router db:migrate

If auth requests hit the wrong port in local dev, ensure auth client/server base URL resolves to the current origin/port.

Reference Loading Map

• Bootstrap and scaffold flow: references/bootstrap-and-scaffold.md
• Runtime exports and usage patterns: references/runtime-api-guide.md
• Billing portal + webhook + idempotent subscription sync: references/billing-webhook-patterns.md
• Troubleshooting and production hardening: references/troubleshooting-and-hardening.md