Better Auth Custom Credentials Plugin

Common errors

• TypeError: credentialsPlugin is not a function

  cause Attempting to import `credentialsPlugin` using CommonJS `require()` syntax or incorrect named import from an ESM-only package.
  fix Ensure you are using ECMAScript Modules (ESM) import syntax: `import { credentialsPlugin } from 'better-auth-custom-credentials';`.

• ZodError: Invalid input

  cause The data sent from the client-side `authClient.signIn.credentials()` call does not conform to the `inputSchema` defined with Zod on the server-side `credentialsPlugin`.
  fix Review your server-side `inputSchema` and ensure the client-side `signIn.credentials` method is sending an object with the exact keys and types expected by the schema.

• Error: Cannot find module 'better-auth' or 'zod'

  cause The `better-auth` or `zod` peer dependencies are not installed in your project.
  fix Install the required peer dependencies: `npm install better-auth zod` or `pnpm add better-auth zod`.

• Type 'Partial<User>' is not assignable to type 'User'. Property 'id' is missing in type 'Partial<User>' but required in type 'User'.

  cause The `user` object returned by the `verify` function does not contain all required properties as defined by your application's `User` type for Better Auth.
  fix Ensure the `user` object returned from `verify` includes all mandatory fields (e.g., `id`, `email`, `name`) that your `better-auth` configuration expects for a `User`.

Warnings

• breaking As a pre-1.0 package (version 0.1.8), the API is subject to frequent and significant breaking changes between minor versions. Always consult the latest README and changelog before upgrading.
  Fix: Review the official GitHub repository for the latest API documentation and migration guides when updating versions. Pin exact versions in `package.json` to prevent unexpected breaks.
• gotcha The `verify` function within `credentialsPlugin` must strictly return an object conforming to `{ ok: boolean; reason?: string; user?: User; meta?: Record<string, any> }` on success or failure. An incorrect return type can lead to authentication failures or incomplete session data.
  Fix: Ensure your `verify` implementation consistently returns an object with an `ok` boolean, an optional `reason` (for failures), and `user` and `meta` (for success) to be picked up by Better Auth's session management.
• gotcha When using `createAuthClient` on the client-side, it is crucial to include `credentials: 'include'` in your `fetch` configuration. Omitting this will prevent cookies (like session tokens) from being sent with requests, leading to unauthenticated requests or session management issues.
  Fix: Modify your `createAuthClient` configuration to always pass `{ credentials: 'include' }` in the `fetch` options: `createAuthClient({ fetch: (url, init) => fetch(url, { ...init, credentials: 'include' }) })`.
• gotcha Forgetting to define a robust `inputSchema` using Zod within the `credentialsPlugin` configuration can lead to insecure or unexpected authentication behavior, as input validation will be absent or incomplete.
  Fix: Always provide a comprehensive `z.object()` schema to the `inputSchema` property of `credentialsPlugin` to define and validate all expected input fields from the client-side form.

Install

• npm install better-auth-custom-credentials npm
• yarn add better-auth-custom-credentials yarn
• pnpm add better-auth-custom-credentials pnpm

Imports

• credentialsPlugin
  wrong:

  const credentialsPlugin = require('better-auth-custom-credentials');

  correct:

  import { credentialsPlugin } from 'better-auth-custom-credentials';

  This is the main server-side plugin for Better Auth, primarily used in ESM contexts.
• extendAuthClientWithCredentials
  wrong:

  const extendAuthClientWithCredentials = require('better-auth-custom-credentials').extendAuthClientWithCredentials;

  correct:

  import { extendAuthClientWithCredentials } from 'better-auth-custom-credentials';

  Used client-side, typically with React/Next.js, to extend the `better-auth` client with credentials methods. Requires `createAuthClient` from `better-auth/react`.
• z

  import { z } from 'zod';

  Zod is a peer dependency and is essential for defining the input schema for the credentials plugin.

Quickstart

Demonstrates client-side setup for `better-auth-custom-credentials`, including extending the auth client, signing in with custom credentials, and retrieving session data.

import { createAuthClient } from 'better-auth/react';
import { extendAuthClientWithCredentials } from 'better-auth-custom-credentials';

// Create a basic Better Auth client, ensuring credentials are included for session management.
// This client will interact with your server-side Better Auth setup.
export const authClient = extendAuthClientWithCredentials(
  createAuthClient({
    fetch: (url, init) => {
      return fetch(url, {
        ...init,
        credentials: 'include', // Important: Ensures cookies are sent with requests
        cache: 'no-store',
      });
    },
  })
);

async function authenticateAndGetSession() {
  console.log('Attempting to sign in with credentials...');
  // Sign in using the credentials method. The input object must match the server-side Zod schema.
  const result = await authClient.signIn.credentials({
    email: 'user@example.com',
    otp: '123456',
    rememberMe: true,
  });

  if (result.ok) {
    console.log('Sign in successful!');
    // Retrieve the session data after successful authentication.
    const { data: session } = await authClient.getSession();
    const jwt = session?.data?.jwt;
    const permissions = session?.data?.permissions;

    console.log('Session Data:', session);
    console.log('JWT:', jwt);
    console.log('Permissions:', permissions);
  } else {
    console.error('Sign in failed:', result.reason);
  }
}

// Example call (in a real app, this would be triggered by a form submission or similar event)
// authenticateAndGetSession();