Preferences

The Preferences plugin allows you to define, read, and write preferences across multiple scopes (e.g., user, project, organization). It supports scoped preferences with optional scopeId, group operations, default values, and encryption for sensitive values.

Installation

npm install @better-auth-extended/preferences

import { betterAuth } from "better-auth";
import { preferences, createPreferenceScope } from "@better-auth-extended/preferences";
import { z } from "zod";

export const auth = betterAuth({
    // ... other config options
    plugins: [
        preferences({
            scopes: {
                user: createPreferenceScope({
                    preferences: {
                        theme: { type: z.enum(["light", "dark", "system"]) },
                        notifications: { type: z.boolean() },
                    },
                    defaultValues: {
                        theme: "system",
                        notifications: false,
                    },
                }),
                project: createPreferenceScope({
                    preferences: {
                        buildChannel: { type: z.enum(["stable", "beta"]) },
                        envSecrets: { type: z.record(z.string(), z.string()), sensitive: true },
                    },
                    requireScopeId: true,
                    groups: {
                        ui: {
                            preferences: {
                                buildChannel: true,
                                envSecrets: true
                            },
                            operations: ["read", "write"],
                        },
                    },
                }),
            },
        }),
    ],
});

import { createAuthClient } from "better-auth/client";
import { preferencesClient } from "@better-auth-extended/preferences/client";

const authClient = createAuthClient({
    plugins: [preferencesClient()],
});

npx @better-auth/cli migrate

npx @better-auth/cli generate

Basic Usage

The Preferences plugin provides several endpoints to manage preferences. You can get and set individual preferences or work with groups of preferences.

Get Preference

Retrieve a single preference value by scope and key.

const { data, error } = await authClient.preferences.user.theme.get({    scopeId,});

const data = await auth.api.getUserThemePreference({    query: {        scopeId,    },});

or

const { data, error } = await authClient.preferences.getPreference({    scope, // required    key, // required    scopeId,});

const data = await auth.api.getPreference({    query: {        scope, // required        key, // required        scopeId,    },});

Set Preference

Set or update a single preference value.

const { data, error } = await authClient.preferences.user.theme.set({    scopeId,    value, // required});

const data = await auth.api.setUserThemePreference({    body: {        scopeId,        value, // required    },});

or

const { data, error } = await authClient.preferences.setPreference({    scope, // required    key, // required    value, // required    scopeId,});

const data = await auth.api.setPreference({    body: {        scope, // required        key, // required        value, // required        scopeId,    },});

Get Group

Retrieve multiple preferences at once using a defined group.

const { data, error } = await authClient.preferences.project.$ui.get({    scopeId,});

const data = await auth.api.getProjectUiPreferences({    query: {        scopeId,    },});

Set Group

Set multiple preferences at once using a defined group.

const { data, error } = await authClient.preferences.project.$ui.set({    scopeId,    values, // required});

const data = await auth.api.setProjectUiPreferences({    body: {        scopeId,        values, // required    },});

Creating Scopes

Define your scopes with their preferences, validation types, defaults, optional groups, and access rules. Each scope and preference automatically generates the corresponding endpoints above.

import { preferences, createPreferenceScope } from "@better-auth-extended/preferences";
import { z } from "zod";

preferences({
    scopes: {
        user: createPreferenceScope({
            preferences: {
                theme: { type: z.enum(["light", "dark", "system"]) },
                notifications: { type: z.boolean() },
            },
            defaultValues: {
                theme: "system",
                notifications: false,
            },
        }),
        project: preferences.createScope({
            preferences: {
                buildChannel: { type: z.enum(["stable", "beta"]) },
                envSecrets: { type: z.record(z.string(), z.string()), sensitive: true },
            },
            requireScopeId: true,
            groups: {
                ui: {
                    preferences: {
                        buildChannel: true,
                        envSecrets: true
                    },
                    operations: ["read", "write"],
                },
            },
        }),
    },
});

Options

preferences: Record<string, { type: StandardSchemaV1; sensitive?: boolean; secret?: string; }> - Object mapping preference keys to their type definitions.

groups: Record<string, { preferences: Partial<Record<keyof preferences, boolean>>; operations?: "read" | "write" | ("read" | "write")[]; }> - Optional groups for batch operations.

defaultValues: Partial<Record<keyof preferences, any | (() => any)>> - Default values for preferences. Can be static values or functions.

canRead: boolean | Permission | (data, ctx) => boolean | Permission | Promise<boolean | Permission> - Permission check for reading preferences.

canWrite: boolean | Permission | (data, ctx) => boolean | Permission | Promise<boolean | Permission> - Permission check for writing preferences.

canWrite: {
    statement: "preferences",
    permissions: ["write"],
};

requireScopeId: boolean - Whether the scope requires a scopeId for all operations.

disableUserBinding: boolean - Whether to disable binding preferences to users.

mergeStrategy: "deep" | "replace" - How to merge default values with stored values.

sensitive: boolean - Whether to encrypt values at rest for the entire scope.

secret: string - Custom secret for encryption/decryption.

Schema

Table Name: preference

Options

scopes: Record<string, PreferenceScopeAttributes> - Object mapping scope names to their configuration.