API reference

Entry points

Import	Contents	Sonner required
better-auth-tarjim	authToast, withAuthToast, createAuthToast, types	Yes — this entry imports Sonner
better-auth-tarjim/translate	translate, messages, types	No

Both entry points ship ESM and CommonJS builds with matching TypeScript declarations.

translate and messages live only in better-auth-tarjim/translate. They are not re-exported from the main entry, because that entry imports Sonner — keeping them out means a consumer who only wants Arabic text never has to install it.

authToast

function authToast(error: unknown, options?: AuthToastOptions): string | number;

Shows toast.error() with the Arabic message and returns Sonner's toast id.

const id = authToast(error, {
  toast: { id: "auth-error", duration: 5000 },
});

The error can be:

• the error object returned by a Better Auth client: { code, message, status }
• a thrown server APIError: { body: { code, message }, status | statusCode }
• an Error from a failed request (offline, DNS, CORS)
• a bare error code string, such as "USER_NOT_FOUND"

withAuthToast

function withAuthToast<T extends { error?: unknown }>(
  promise: Promise<T>,
  options?: AuthToastOptions,
): Promise<T>;

Awaits a Better Auth call, toasts on failure, and returns the original result untouched.

• If the promise resolves with a truthy error, it is toasted.
• If the promise rejects (network failure), the rejection is toasted and then re-thrown.

const result = await withAuthToast(authClient.signIn.email({ email, password }));

createAuthToast

function createAuthToast(defaults?: AuthToastOptions): {
  authToast: (error: unknown, options?: AuthToastOptions) => string | number;
  withAuthToast: <T extends { error?: unknown }>(
    promise: Promise<T>,
    options?: AuthToastOptions,
  ) => Promise<T>;
  translate: (error: unknown, options?: TranslateOptions) => string;
};

Returns the three helpers with your defaults applied. Per-call options win. overrides and toast are merged key by key, so a call can add to the defaults without replacing them.

export const { authToast } = createAuthToast({
  overrides: { USER_ALREADY_EXISTS: "هذا البريد مسجّل لدينا" },
  toast: { duration: 5000 },
});

translate

function translate(error: unknown, options?: TranslateOptions): string;

Returns the Arabic message for any supported error shape. Use it with another toast library, for inline form errors, or on the server.

import { translate } from "better-auth-tarjim/translate";

translate({ code: "INVALID_EMAIL_OR_PASSWORD" });

See how an error is resolved for the lookup order.

Options

TranslateOptions

Option	Type	Default	Description
overrides	Record<string, string>	undefined	Your own messages by code. They win over the built-in Arabic ones. Empty strings are ignored. Also used for custom plugin codes.
fallback	string	"حدث خطأ غير متوقع، حاول مرة أخرى"	Replaces the generic fallback message.
showOriginal	boolean	false	For unknown codes, show the server's original English message instead of the fallback.

AuthToastOptions

AuthToastOptions extends TranslateOptions with one field:

Option	Type	Description
toast	ExternalToast	Passed straight to Sonner's toast.error(): id, duration, description, action, and so on.

messages

const messages: Readonly<Record<ErrorCode, string>>;

The built-in Arabic dictionary: a read-only map from every Better Auth error code to its message. Use it when you need the raw text without calling translate:

import { messages } from "better-auth-tarjim/translate";

messages.INVALID_EMAIL_OR_PASSWORD;

Because it is typed by ErrorCode, a mistyped code does not compile.

ErrorCode

type ErrorCode = "ACCESS_DENIED" | "ACCOUNT_NOT_FOUND" | /* ... */;

A union of every error code extracted from the Better Auth release this version was generated from. It is regenerated by npm run sync, so it stays aligned with Better Auth. See the full list.

Fallback messages

These messages are not tied to a Better Auth code. They apply when no code matches:

Situation	Used when
Too many requests	The response status is 429.
Network failure	The request never reached the server (offline, DNS, CORS).
Server error	The response status is 5xx and the code is unknown.
Generic fallback	Nothing else matched. Replaceable with fallback.