Skip to main content
Metadata configuration allows you to customize the branding, theme, and features of your self-hosted Better Auth Studio instance.

​
Configuration

Configure metadata in your studio.config.ts:
studio.config.ts
import type { StudioConfig } from "better-auth-studio";
import { auth } from "./lib/auth";

const config: StudioConfig = {
  auth,
  basePath: "/api/studio",
  metadata: {
    title: "Admin Dashboard",
    logo: "/logo.png",
    favicon: "/favicon.ico",
    theme: "dark",
    company: {
      name: "Acme Inc",
      website: "https://acme.com",
      supportEmail: "[email protected]",
    },
    colors: {
      primary: "#3b82f6",
      secondary: "#8b5cf6",
      accent: "#10b981",
    },
    features: {
      users: true,
      sessions: true,
      organizations: true,
      analytics: true,
      tools: true,
      security: true,
    },
    links: [
      { label: "Documentation", url: "https://docs.acme.com" },
      { label: "Support", url: "https://support.acme.com" },
    ],
    custom: {
      // Any custom metadata
    },
  },
};

export default config;

​
Metadata Options

​
Basic Information

​
metadata.title
string
The title displayed in the browser tab and headerDefault: "Better Auth Studio"
metadata: {
  title: "Admin Dashboard"
}
URL or path to your logo image. Displayed in the sidebar and header.
metadata: {
  logo: "/images/company-logo.png"
}
​
metadata.favicon
string
URL or path to your favicon
metadata: {
  favicon: "/favicon.ico"
}

​
Theme

​
metadata.theme
'dark' | 'light' | 'auto'
The color theme for Studio
  • "dark": Dark mode
  • "light": Light mode
  • "auto": Match system preference
Default: "dark"
metadata: {
  theme: "auto" // Respects user's system theme
}

​
Company Information

​
metadata.company
object
Company information displayed in the UI
company: {
  name: "Acme Inc",
  website: "https://acme.com",
  supportEmail: "[email protected]",
}
​
metadata.company.name
string
Your company or product name
​
metadata.company.website
string
Your company website URL
​
metadata.company.supportEmail
string
Support email address for users to contact

​
Colors

​
metadata.colors
object
Custom color scheme for Studio
colors: {
  primary: "#3b82f6",   // Blue
  secondary: "#8b5cf6", // Purple
  accent: "#10b981",    // Green
}
​
metadata.colors.primary
string
Primary brand color (hex format)
​
metadata.colors.secondary
string
Secondary brand color (hex format)
​
metadata.colors.accent
string
Accent color for highlights and CTAs (hex format)

​
Feature Toggles

​
metadata.features
object
Enable or disable Studio features
features: {
  users: true,
  sessions: true,
  organizations: false, // Hide organizations if not using plugin
  analytics: true,
  tools: true,
  security: true,
}
​
metadata.features.users
boolean
Show/hide the Users sectionDefault: true
​
metadata.features.sessions
boolean
Show/hide the Sessions sectionDefault: true
​
metadata.features.organizations
boolean
Show/hide the Organizations sectionDefault: true
​
metadata.features.analytics
boolean
Show/hide Analytics/DashboardDefault: true
​
metadata.features.tools
boolean
Show/hide the Tools sectionDefault: true
​
metadata.features.security
boolean
Show/hide Security featuresDefault: true
​
metadata.links
Array<{ label: string; url: string }>
Custom navigation links displayed in the UI
links: [
  { label: "Documentation", url: "https://docs.example.com" },
  { label: "API Reference", url: "https://api.example.com" },
  { label: "Support", url: "https://support.example.com" },
  { label: "Status", url: "https://status.example.com" },
]

​
Custom Data

​
metadata.custom
Record<string, any>
Any custom metadata for your application
custom: {
  version: "2.0.0",
  environment: "production",
  region: "us-east-1",
  customFeatureFlag: true,
}

​
TypeScript Type Definition

type StudioMetadata = {
  title?: string;
  logo?: string;
  favicon?: string;
  company?: {
    name?: string;
    website?: string;
    supportEmail?: string;
  };
  theme?: "dark" | "light" | "auto";
  colors?: {
    primary?: string;
    secondary?: string;
    accent?: string;
  };
  features?: {
    users?: boolean;
    sessions?: boolean;
    organizations?: boolean;
    analytics?: boolean;
    tools?: boolean;
    security?: boolean;
  };
  links?: Array<{ label: string; url: string }>;
  custom?: Record<string, any>;
};

​
Example Configurations

​
Minimal Branding

studio.config.ts
const config: StudioConfig = {
  auth,
  basePath: "/api/studio",
  metadata: {
    title: "Admin Panel",
    theme: "dark",
  },
};

​
Complete Customization

studio.config.ts
const config: StudioConfig = {
  auth,
  basePath: "/api/studio",
  metadata: {
    title: "Acme Admin Dashboard",
    logo: "https://cdn.acme.com/logo.svg",
    favicon: "https://cdn.acme.com/favicon.ico",
    theme: "auto",
    company: {
      name: "Acme Corporation",
      website: "https://acme.com",
      supportEmail: "[email protected]",
    },
    colors: {
      primary: "#1e40af",
      secondary: "#7c3aed",
      accent: "#059669",
    },
    features: {
      users: true,
      sessions: true,
      organizations: true,
      analytics: true,
      tools: true,
      security: true,
    },
    links: [
      { label: "Main Site", url: "https://acme.com" },
      { label: "Docs", url: "https://docs.acme.com" },
      { label: "Support", url: "https://help.acme.com" },
      { label: "Status", url: "https://status.acme.com" },
    ],
    custom: {
      version: process.env.APP_VERSION,
      deployedAt: new Date().toISOString(),
      features: {
        betaFeatures: true,
      },
    },
  },
};

​
Feature-Specific Configuration

Disable features you’re not using:
studio.config.ts
const config: StudioConfig = {
  auth,
  basePath: "/api/studio",
  metadata: {
    title: "User Management",
    features: {
      users: true,
      sessions: true,
      organizations: false, // Not using organization plugin
      analytics: false,     // Disable analytics
      tools: true,
      security: true,
    },
  },
};

​
Asset Hosting

​
Local Assets

Place assets in your public directory: 
project/
├── public/
│   ├── logo.png
│   ├── favicon.ico
│   └── images/
│       └── company-logo.svg
└── studio.config.ts
studio.config.ts
metadata: {
  logo: "/logo.png",
  favicon: "/favicon.ico",
}

​
CDN Assets

studio.config.ts
metadata: {
  logo: "https://cdn.example.com/logo.svg",
  favicon: "https://cdn.example.com/favicon.ico",
}

​
Environment-Based Configuration

studio.config.ts
const isDev = process.env.NODE_ENV === "development";

const config: StudioConfig = {
  auth,
  basePath: "/api/studio",
  metadata: {
    title: isDev ? "Admin (Dev)" : "Admin Dashboard",
    theme: isDev ? "light" : "dark",
    company: {
      name: process.env.COMPANY_NAME,
      website: process.env.COMPANY_WEBSITE,
      supportEmail: process.env.SUPPORT_EMAIL,
    },
    custom: {
      environment: process.env.NODE_ENV,
      version: process.env.APP_VERSION,
    },
  },
};

export default config;

​
Best Practices

Branding Tips:
  • Use SVG logos for crisp rendering at any size
  • Ensure logo has transparent background for theme compatibility
  • Test colors in both light and dark modes if using theme: "auto"
  • Keep custom links to 4-5 items for clean navigation
  • Use environment variables for environment-specific values

​
Accessibility

When customizing colors, ensure:
  • Sufficient contrast ratios (WCAG AA: 4.5:1 for normal text)
  • Colors are distinguishable for color-blind users
  • Text remains readable on both light and dark backgrounds

Build docs developers (and LLMs) love

Get started for freeTalk to us