playbooks

home / skills / bobmatnyc / claude-mpm-skills / better-auth-authentication

better-auth-authentication skill

/toolchains/platforms/auth/better-auth/better-auth-authentication

This skill helps you implement robust email/password and social authentication flows in TypeScript apps, with sign-up, sign-in, verification, and redirects.

npx playbooks add skill bobmatnyc/claude-mpm-skills --skill better-auth-authentication

Review the files below or copy the command above to add this skill to your agents.

Files (4)
SKILL.md
2.6 KB
---
name: better-auth-authentication
description: Better Auth authentication flows for TypeScript apps. Use when enabling email/password auth, configuring social providers, or implementing sign-up, sign-in, and verification flows.
progressive_disclosure:
  entry_point:
    summary: "Better Auth authentication flows for TypeScript apps. Use when enabling email/password auth, configuring social providers, or implementing sign-up, sign-in, and verification flows."
    when_to_use: "When implementing authentication, authorization, or security."
    quick_start: "1. Review the core concepts below. 2. Apply patterns to your use case. 3. Follow best practices for implementation."
  references:
    - email-password.md
    - providers.md
---
# Better Auth Authentication

## Goals
- Enable email/password authentication and social providers.
- Implement sign-up, sign-in, sign-out, and verification flows.
- Handle redirects and errors consistently.

## Quick start
1. Enable `emailAndPassword` and configure `socialProviders`.
2. Create a client with `createAuthClient`.
3. Use `signUp.email`, `signIn.email`, `signIn.social`, and `signOut` on the client.

```ts
import { betterAuth } from "better-auth";

export const auth = betterAuth({
  emailAndPassword: { enabled: true },
  socialProviders: {
    github: {
      clientId: process.env.GITHUB_CLIENT_ID as string,
      clientSecret: process.env.GITHUB_CLIENT_SECRET as string,
    },
  },
});
```

```ts
import { createAuthClient } from "better-auth/client";

const authClient = createAuthClient();

await authClient.signUp.email({
  email,
  password,
  name,
});

await authClient.signIn.email({
  email,
  password,
  callbackURL: "/dashboard",
});

await authClient.signIn.social({
  provider: "github",
  callbackURL: "/dashboard",
});

await authClient.signOut();
```

## Email verification
- Provide `emailVerification.sendVerificationEmail` to send the verification link.
- Use `emailAndPassword.requireEmailVerification` to enforce verification before sign-in.

## Social providers
- Configure providers in `socialProviders` with provider-specific credentials.
- Use `signIn.social` to start OAuth flows.
- Pass `callbackURL`, `errorCallbackURL`, and `newUserCallbackURL` for redirects.

## Guardrails
- Call client methods from the client only.
- Keep secrets in server-only env variables.
- Use `rememberMe` to control persistent sessions on email/password sign-in.

## References
- `toolchains/platforms/auth/better-auth/better-auth-authentication/references/email-password.md`
- `toolchains/platforms/auth/better-auth/better-auth-authentication/references/providers.md`

Overview

This skill implements Better Auth authentication flows for TypeScript apps, enabling email/password and social provider sign-in with built-in sign-up, sign-out, and verification support. It focuses on predictable redirects, error handling, and session control to simplify integrating authentication into web apps. The guidance is practical and oriented toward client/server separation and secure secret handling.

How this skill works

Configure the auth system by enabling email/password and registering social providers with server-only credentials. Create a client via createAuthClient and call client methods like signUp.email, signIn.email, signIn.social, and signOut from the browser. Email verification is supported via sendVerificationEmail and can be enforced before sign-in. OAuth flows use callback URLs for success, error, and new-user redirects.

When to use it

  • Adding email/password sign-up and sign-in to a TypeScript web app
  • Integrating GitHub, Google, or other OAuth providers for social sign-in
  • Requiring email verification before granting access
  • Implementing consistent redirect and error handling after auth actions
  • Managing session persistence with rememberMe options

Best practices

  • Keep client-side code limited to createAuthClient and client method calls; never expose secrets in the browser
  • Store provider credentials and email-sending secrets in server-only environment variables
  • Use callbackURL, errorCallbackURL, and newUserCallbackURL to control user flow after OAuth
  • Enable emailAndPassword.requireEmailVerification if you must confirm emails before account access
  • Use rememberMe for explicit persistent sessions and clear UX around session length

Example use cases

  • Standard sign-up and sign-in flow with email/password and email verification enforcement
  • GitHub social sign-in that redirects new users to an onboarding page via newUserCallbackURL
  • Single sign-out action that terminates the session on the client and redirects to a post-logout page
  • Server-side code sends verification emails and the client triggers signIn.email only after verification

FAQ

Where should I keep OAuth client IDs and secrets?

Store them in server-only environment variables; never expose them in client bundles.

Can I require email verification before sign-in?

Yes — enable emailAndPassword.requireEmailVerification to block sign-ins until verification is complete.