Skip to content

secondsky/claude-skills / plugins/better-auth/skills/better-auth

better-auth

Verified

Skill for integrating Better Auth - comprehensive TypeScript authentication framework for Cloudflare D1, Next.js, Nuxt, and 15+ frameworks. Use when adding auth, encountering D1 adapter errors, or implementing OAuth/2FA/RBAC features.

FileKindSize
SKILL.mdskill md29.2 KB
assets/auth-flow-diagram.mdmarkdown24.0 KB
references/advanced-features.mdmarkdown14.7 KB
references/cloudflare-worker-drizzle.tsscript12.7 KB
references/cloudflare-worker-kysely.tsscript9.7 KB
references/configuration-guide.mdmarkdown10.7 KB
references/database-schema.tsscript10.8 KB
references/databases/mongodb.mdmarkdown5.3 KB
references/databases/mysql.mdmarkdown6.8 KB
references/databases/postgresql.mdmarkdown8.4 KB
references/error-catalog.mdmarkdown12.9 KB
references/framework-comparison.mdmarkdown8.2 KB
references/frameworks/api-frameworks.mdmarkdown9.2 KB
references/frameworks/expo-mobile.mdmarkdown8.7 KB
references/frameworks/nextjs.mdmarkdown5.4 KB
references/frameworks/nuxt.mdmarkdown6.0 KB
references/frameworks/remix.mdmarkdown6.1 KB
references/frameworks/sveltekit.mdmarkdown6.3 KB
references/integrations/electron.mdmarkdown8.2 KB
references/migration-guide-1.4.0.mdmarkdown23.2 KB
references/migration-guide-1.5.0.mdmarkdown6.3 KB
references/nextjs/README.mdmarkdown1.1 KB
references/nextjs/postgres-example.tsscript4.0 KB
references/plugins/api-tokens.mdmarkdown10.0 KB
references/plugins/authentication.mdmarkdown9.2 KB
references/plugins/enterprise.mdmarkdown9.1 KB
references/plugins/payments.mdmarkdown8.0 KB
references/plugins/sso.mdmarkdown9.4 KB
references/plugins/test-utils.mdmarkdown5.5 KB
references/react-client-hooks.tsxother12.8 KB
references/setup-guide.mdmarkdown8.9 KB
references/v1.4-features.mdmarkdown8.2 KB
references/v1.5-features.mdmarkdown11.0 KB
references/v1.6-features.mdmarkdown6.1 KB
scripts/generate-secret.shexecutablescript2.0 KB
scripts/setup-d1-drizzle.shexecutablescript10.2 KB
scripts/test-auth-health.shexecutablescript2.1 KB
scripts/validate-config.tsscript4.3 KB

references/framework-comparison.md

View on GitHub
# Better-Auth vs Alternatives: Complete Comparison

**Last Updated**: 2026-08-03
**better-auth Version**: 1.6.0

---

## Overview

This guide compares better-auth with popular authentication alternatives to help choose the right solution for your project.

---

## Feature Comparison Matrix

| Feature | better-auth 1.4+ | Clerk | Auth.js |
|---------|------------------|-------|---------|
| **Hosting** | Self-hosted | Third-party | Self-hosted |
| **Cost** | Free (OSS) | $25/mo+ | Free (OSS) |
| **License** | MIT | Proprietary | ISC |
| **Cloudflare D1** | ✅ Drizzle/Kysely | ❌ No | ✅ Adapter |
| **Social Auth** | ✅ 10+ providers | ✅ Many | ✅ Many |
| **2FA/Passkeys** | ✅ Plugin | ✅ Built-in | ⚠️ Limited |
| **Organizations** | ✅ Plugin | ✅ Built-in | ❌ No |
| **RBAC** | ✅ Plugin | ✅ Built-in | ⚠️ Manual |
| **Vendor Lock-in** | ✅ None | ❌ High | ✅ None |
| **Stateless Sessions** | ✅ v1.4.0+ | ✅ | ⚠️ Limited |
| **Database Joins** | ✅ v1.4.0+ (2-3x faster) | N/A | ❌ |
| **API Keys** | ✅ v1.4.0+ | ✅ | ❌ |
| **SCIM Provisioning** | ✅ v1.4.0+ | ✅ | ❌ |
| **ESM-only** | ✅ v1.4.0+ | ❌ CJS + ESM | ❌ CJS + ESM |
| **Migration Required** | ⚠️ v1.3 → v1.4 | N/A (managed) | Varies |

---

## Detailed Comparison

### better-auth (v1.6.0)

**Strengths**:
- ✅ Self-hosted with full control over data
- ✅ Modern ESM-first architecture (v1.4.0+)
- ✅ Native Cloudflare D1 support via Drizzle/Kysely
- ✅ Database joins (2-3x performance boost in v1.4.0+)
- ✅ Stateless sessions with JWE encryption
- ✅ No vendor lock-in (open source MIT)
- ✅ Plugin ecosystem (2FA, passkeys, organizations, API keys, SCIM)
- ✅ Active development with frequent updates
- ✅ TypeScript-first with excellent type safety

**Weaknesses**:
- ⚠️ Self-hosted means you manage infrastructure
- ⚠️ Smaller community vs Auth.js/Clerk
- ⚠️ v1.4.0 introduced breaking changes (ESM-only)
- ⚠️ Requires Drizzle or Kysely for D1 (no direct adapter)

**Best For**:
- Cloudflare Workers/D1 projects
- Teams wanting full control and no vendor lock-in
- Projects requiring modern ESM architecture
- Apps needing stateless sessions or database joins
- Startups avoiding recurring SaaS costs

**v1.4.0+ New Features**:
- Database joins for 2-3x faster queries
- Stateless sessions with JWT
- API key authentication plugin
- SCIM provisioning for enterprise
- Vercel OAuth provider
- Trusted proxy headers support
- Improved OpenAPI schema support

---

### Clerk

**Strengths**:
- ✅ Fully managed service (zero infrastructure work)
- ✅ Beautiful pre-built UI components
- ✅ Excellent developer experience
- ✅ Organizations, RBAC, webhooks built-in
- ✅ Fastest time to production
- ✅ Great documentation and support
- ✅ Multi-tenancy out of the box

**Weaknesses**:
- ❌ Proprietary/closed source
- ❌ High cost ($25/mo minimum, scales with users)
- ❌ Vendor lock-in (migration difficult)
- ❌ No Cloudflare D1 support
- ❌ Data stored on Clerk's servers
- ❌ Limited customization vs self-hosted

**Best For**:
- Rapid prototyping and MVPs
- Teams prioritizing speed over cost
- Projects needing managed service
- Apps with budget for SaaS
- Non-Cloudflare infrastructure

---

### Auth.js (formerly NextAuth.js)

**Strengths**:
- ✅ Self-hosted and open source (ISC license)
- ✅ Large community and ecosystem
- ✅ Many adapters (PostgreSQL, MySQL, MongoDB, etc.)
- ✅ Tight Next.js integration
- ✅ Mature and battle-tested
- ✅ Free and no vendor lock-in

**Weaknesses**:
- ⚠️ Primarily designed for Next.js (less ideal elsewhere)
- ❌ No native organizations or RBAC
- ❌ No stateless sessions (database required)
- ❌ No database joins optimization
- ❌ Slower development pace vs better-auth
- ⚠️ Cloudflare D1 adapter exists but less optimized

**Best For**:
- Next.js applications
- Teams already familiar with Auth.js
- Projects needing basic authentication only
- Non-Cloudflare databases (PostgreSQL, MySQL)

---

## Recommendations by Use Case

### Use better-auth if:
- ✅ Building on **Cloudflare Workers + D1**
- ✅ Want **full control** over auth logic and data
- ✅ Need **modern ESM architecture**
- ✅ Require **stateless sessions** or **database joins**
- ✅ Avoiding **vendor lock-in** and SaaS costs
- ✅ Need **API key authentication** (v1.4.0+)
- ✅ Building with **Drizzle ORM or Kysely**
- ✅ Want **plugin-based extensibility**

### Use Clerk if:
- ✅ Need **fastest time to market**
- ✅ Want **fully managed service** (zero infra work)
- ✅ Budget allows for **SaaS pricing**
- ✅ Need **pre-built UI components**
- ✅ Require **enterprise features** out of the box
- ❌ NOT using Cloudflare D1
- ✅ Prioritize **developer experience** over cost

### Use Auth.js if:
- ✅ Already using **Next.js**
- ✅ Need **basic authentication** only
- ✅ Familiar with Auth.js ecosystem
- ✅ Using **PostgreSQL, MySQL, or MongoDB**
- ❌ Don't need organizations or RBAC
- ❌ NOT using Cloudflare Workers/D1

---

## Migration Paths

### From Clerk to better-auth

**Effort**: High (3-5 days)
**Considerations**:
- Export user data from Clerk
- Re-implement auth UI (Clerk's is pre-built)
- Migrate to self-hosted infrastructure
- Update authentication calls throughout app
- **Benefit**: Eliminate $25+/mo cost, gain full control

**Steps**:
1. Export users from Clerk dashboard
2. Set up better-auth with D1 + Drizzle
3. Migrate user data to D1 (hash passwords if needed)
4. Replace Clerk's `useAuth()` with `authClient.useSession()`
5. Update OAuth provider settings (callback URLs)
6. Deploy and test thoroughly

---

### From Auth.js to better-auth

**Effort**: Medium (2-3 days)
**Considerations**:
- Both are self-hosted (infrastructure similar)
- Database migration required
- API calls change but patterns familiar
- **Benefit**: Better Cloudflare D1 support, database joins, stateless sessions

**Steps**:
1. Set up better-auth alongside Auth.js (parallel)
2. Migrate database schema to Drizzle/Kysely
3. Export/import user data
4. Update authentication calls (similar patterns)
5. Switch over and retire Auth.js
6. Enable v1.4.0+ features (joins, stateless sessions)

---

### From better-auth v1.3.x to v1.4.0+

**Effort**: Low-Medium (4-8 hours)
**Breaking Changes**: ESM-only, API renames, callback signatures
**See**: `migration-guide-1.4.0.md` for complete guide

---

## Cost Analysis (5-Year TCO)

### Scenario: 10,000 active users

| Solution | Year 1 | Year 5 | Total (5yr) | Notes |
|----------|--------|--------|-------------|-------|
| **better-auth** | $0-500 | $0-500 | $0-2,500 | Cloudflare Workers cost only (~$5/mo) |
| **Clerk** | $3,000+ | $6,000+ | $24,000+ | Starts $25/mo, scales with users |
| **Auth.js** | $0-500 | $0-500 | $0-2,500 | Self-hosted infra cost only |

**Winner**: better-auth or Auth.js (tie for cost)

---

## Performance Comparison

### Authentication Latency (p95)

| Solution | Cold Start | Warm | Notes |
|----------|------------|------|-------|
| **better-auth (v1.4.0+)** | ~150ms | ~15ms | Cloudflare Workers edge + database joins |
| **Clerk** | ~200ms | ~25ms | Managed service + network latency |
| **Auth.js** | ~300ms | ~30ms | Traditional server architecture |

**Winner**: better-auth (edge compute + optimized queries)

---

## Community & Support

### GitHub Activity (2025-11-27)

| Solution | Stars | Contributors | Issues (open) | Last Release |
|----------|-------|--------------|---------------|--------------|
| **better-auth** | 22.4k | 45+ | 120 | v1.4.3 (2025-11) |
| **Clerk** | N/A (closed source) | N/A | N/A (support tickets) | Continuous |
| **Auth.js** | 24.1k | 600+ | 180 | v5.0 (2025-09) |

---

## Final Recommendation

**For Cloudflare Workers + D1**: **better-auth** is the clear winner
- Native support, modern architecture, database joins, no cost

**For fastest launch**: **Clerk** wins
- Managed service, pre-built UI, fastest to production

**For Next.js only**: **Auth.js** is solid
- Tight integration, mature ecosystem, free

**For modern TypeScript projects**: **better-auth v1.4.0+**
- ESM-first, type-safe, plugin ecosystem, no vendor lock-in

---

## Additional Resources

- **better-auth**: https://better-auth.com
- **Clerk**: https://clerk.com
- **Auth.js**: https://authjs.dev

---

**Last updated**: 2026-08-03 | better-auth v1.6.0
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall