English for Better Auth Developers

Better Auth is a framework-agnostic, TypeScript-first authentication library that ships without the vendor lock-in of a hosted auth provider — you own the database schema and the session logic, but get plugins and adapters that cover most of the hard parts. Because auth code review touches security, session lifecycle, and plugin composition all at once, the vocabulary matters more than in most libraries. Here’s the English you need to discuss it clearly with your team.

---

Sessions and Core Concepts

Session management — the logic that creates, validates, refreshes, and revokes a user’s authenticated session, typically backed by a cookie or token stored server-side. “We switched from JWT-only sessions to database-backed sessions so we could revoke access immediately when a user is deactivated.”

Framework-agnostic — describing a library that isn’t tied to one specific framework (Next.js, SvelteKit, Express) and instead exposes adapters for each. “Better Auth being framework-agnostic meant we could reuse the same auth logic when we split the admin panel into its own SvelteKit app.”

Session revocation — explicitly invalidating an active session before its natural expiry, usually triggered by a password change or an admin action. “On password reset, we call session revocation for every other active session — otherwise a stolen session token would still work.”

---

Adapters and Providers

Adapter

An adapter connects Better Auth’s core logic to a specific database or ORM (Prisma, Drizzle, Kysely), translating its internal calls into that database’s query language.

“We’re using the Drizzle adapter, so switching the underlying database engine later shouldn’t require touching any auth code.”

Provider

A provider is a specific authentication method — email/password, a social login like GitHub or Google, or a magic link — that a user can use to sign in.

“Enabling the GitHub provider took three config lines and an OAuth app registration — no custom OAuth flow to write by hand.”

Plugin

A plugin extends Better Auth’s core with optional functionality, like two-factor auth, organizations, or rate limiting, without bloating the base install.

“We only pulled in the two-factor plugin and the organizations plugin — the core package stays small if you don’t need the rest.”

---

Hooks and Extensibility

Hook — a function that runs at a specific point in the auth lifecycle (before sign-up, after sign-in) so you can attach custom logic without forking the library.

“We added an after-sign-up hook to send a welcome email — it fires automatically once Better Auth confirms the account was created.”

Middleware integration — wiring Better Auth’s session-check logic into your framework’s middleware layer so protected routes are guarded consistently.

“The middleware integration rejects unauthenticated requests before they even reach the route handler, so we don’t duplicate that check in every endpoint.”

Database schema migration — the process of applying Better Auth’s required tables (users, sessions, accounts) to your existing database, usually via its CLI.

“Running the schema migration added the session and account tables automatically — we didn’t have to hand-write the auth schema.”

---

Explaining Better Auth to a Team

Situation	Phrase
Justifying the choice over a hosted provider	“Since we need full control over the session store for compliance reasons, a self-hosted library like Better Auth fits better than a managed service.”
Explaining plugin architecture	“Two-factor auth is opt-in via a plugin, so teams that don’t need it aren’t paying the bundle-size cost.”
Describing adapter flexibility	“The adapter layer means we’re not locked into Prisma — we could move to Drizzle without rewriting the auth flow.”
Discussing session security	“We revoke all other sessions on password change — that’s standard session-revocation practice for account security.”

Common Mistakes

• Saying “provider” when you mean “adapter” — a provider is a login method (GitHub, email), an adapter is a database connector; mixing them confuses config discussions.
• Treating hooks as middleware — hooks fire at specific lifecycle events, while middleware runs on every matching request; they solve different problems.
• Assuming “framework-agnostic” means “zero setup” — it still requires an adapter and framework-specific wiring, just not a full rewrite per framework.

Practice Exercise

1. Explain, in two sentences, the difference between a Better Auth provider and an adapter to a teammate unfamiliar with the library.
2. Write a short PR description for adding a new OAuth provider and an after-sign-in hook that logs the login event.
3. Draft a message justifying why the team chose a self-hosted auth library over a hosted service like Auth0, focused on data ownership.

Related Resources

• English for Clerk Authentication Developers
• English for Supabase Developers
• English for OpenFGA Developers

Navigating the Nuances: Beyond Literal Translation

The core of effective communication within a development team using tools like Better Auth hinges on more than just direct translation. It’s about conveying intent, suggesting improvements, and collaboratively shaping solutions – all through precise language. A common pitfall for non-native English speakers is over-literal translation, which can result in awkward phrasing or misunderstandings. For example, translating “Let’s refactor this” directly might feel unnatural to someone accustomed to a more literal approach to descriptions. It’s crucial to understand the cultural context of professional development discussions and adopt the appropriate vocabulary.

Consider a scenario: Sarah is reviewing David’s pull request for integrating a new OAuth2 provider into their application. David writes, “I added the Google provider.” While technically correct, it lacks detail and doesn’t convey the full picture to Sarah. A more effective phrasing would be, “This is great! Let’s ensure we’ve correctly implemented the OAuth2 flow using the latest best practices for security and error handling – specifically around token refresh strategies.” Notice how that version proactively addresses potential issues and invites collaboration instead of simply stating a fact. Similarly, a Slack message requesting clarification shouldn’t just be “What is this?”. Instead, “Could you elaborate on the reasoning behind choosing this particular provider adapter and its integration with our existing authentication hooks?” demonstrates a deeper engagement and seeks to understand David’s thought process. Focusing on action-oriented verbs (“implement,” “validate,” “optimize”) and precise terminology (“provider adapter,” “authentication hook”) will dramatically improve your ability to contribute effectively.

Another important element is acknowledging potential ambiguity. Don’t hesitate to ask clarifying questions, even if they seem obvious to others. The phrase “Could you clarify the expected behavior in edge cases?” is far more productive than silently assuming a particular outcome. Remember, asking for clarification demonstrates attention to detail and commitment to producing high-quality code – traits highly valued by experienced developers. It’s about building shared understanding, not just conveying information.

# Example: Verifying Adapter Configuration using curl

curl -s https://api.betterauth.com/adapters/{adapter_id}/config | jq '.status'

This command demonstrates a practical example of verifying adapter configuration – something often discussed during code reviews or troubleshooting sessions. Understanding the output from tools like jq and being able to articulate its implications is key.