Skip to main content

​
Overview

This guide covers all available configuration options for your application using the createConfig function. Required fields are marked as such, while all others are optional.

​
Basic Settings

​
name (Required)

The name of your application. This is used for the website title, emails, and other branding elements throughout your app. 
const config = createConfig({
  name: "My Application", // Required string
  // ... other config
})

​
description (Required)

A brief description of your application. This appears in meta tags, search results, and other places where your app is described. 
const config = createConfig({
  description: "My Application description", // Required string
  // ... other config
})

​
socials (Optional)

Social media links for your application. These are displayed in the website footer and can be used for sharing and promotion. Only include the social platforms you actually use. 
const config = createConfig({
  socials: {
    twitter: "https://x.com/myapplication",
    instagram: "https://instagram.com/myapplication",
    // Available icons are defined in your socialIcons component
  },
  // ... other config
})

​
Payments (Required)

Configure payment plans and subscription features for your application. The entire payments object is required.

​
advantages (Required)

Define the feature advantages that differentiate your pricing plans. Each advantage must be defined as either "number" or "boolean" type. 
const config = createConfig({
  payments: {
    advantages: {
      maxUsers: "number",        // Will be typed as number in products
      canDoSomething: "boolean", // Will be typed as boolean in products
      // Only "number" and "boolean" string literals are allowed
    },
    // ... other payment config
  },
  // ... other config
})

​
defaultProduct (Required)

The free or default plan that users start with. This should include basic advantages that apply to all users. Note that productId is not required for the default product. 
const config = createConfig({
  payments: {
    advantages: {
      maxUsers: "number",
      canDoSomething: "boolean",
    },
    defaultProduct: {
      name: "Free",
      advantages: {
        maxUsers: 1,              // Type inferred as number from advantages definition
        canDoSomething: false     // Type inferred as boolean from advantages definition
      }
    },
    // ... other payment config
  },
  // ... other config
})

​
products (Required)

Define your paid subscription plans. Each product must have both production and development product IDs from your payment provider, and advantages that match your advantages definition. 
const config = createConfig({
  payments: {
    advantages: {
      maxUsers: "number",
      canDoSomething: "boolean",
    },
    defaultProduct: {
      name: "Free",
      advantages: { maxUsers: 1, canDoSomething: false }
    },
    products: {
      premium: {
        productId: {
          production: "prod_xxxxx",     // Required: Stripe/payment provider production ID
          development: "price_test_xxx" // Required: Stripe/payment provider test ID
        },
        name: "Premium",
        advantages: {
          maxUsers: 10,           // Must match type from advantages definition
          canDoSomething: true    // Must match type from advantages definition
        }
      },
      // Add more products as needed
    }
  },
  // ... other config
})

​
Authentication (Required)

Configure how users can sign in to your application. The auth object is required, but its properties are optional. Enable passwordless authentication via email magic links. When enabled, the login page will show an email input for magic link authentication. 
const config = createConfig({
  auth: {
    magicLink: true // Optional: defaults to false if not specified
  },
  // ... other config
})

​
socialProviders (Optional)

Array of social OAuth providers for authentication. The login page will display a button for each enabled provider. The available providers are defined by your SocialProvider type. 
const config = createConfig({
  auth: {
    socialProviders: ["google", "github"] // Optional: array of SocialProvider values
  },
  // ... other config
})

​
Secondary Storage (Optional)

Configure additional storage and caching features for improved performance. Uses Upstash Redis for caching sessions and implementing rate limiting. When enabled, sessions are cached in Redis and rate limiting is handled by Upstash. If not set, sessions will be cached using cookies and the default rate limiter from Better Auth will be used instead.

​
secondaryStorage

Enable secondary storage features like caching and rate limiting. This is recommended for production applications. 
const config = createConfig({
  secondaryStorage: {
    enabled: true // Required if secondaryStorage is provided
  },
  // ... other config
})

​
rateLimit (Optional)

Configure request rate limiting to protect your application from abuse. You can set different limits for page requests and API requests. This is only available when secondaryStorage is enabled. Default values:
  • page: For page requests
    • max: 40 requests
    • window: 60 seconds
  • api: For API requests
    • max: 10 requests
    • window: 20 seconds
const config = createConfig({
  secondaryStorage: {
    enabled: true,
    rateLimit: {
      page: {
        max: 40,    // Maximum 40 page requests
        window: 60  // Per 60-second window (in seconds)
      },
      api: {
        max: 10,    // Maximum 10 API requests  
        window: 20  // Per 20-second window (in seconds)
      }
    }
  },
  // ... other config
})
Note: Rate limiting is only enabled in production mode when secondary storage is enabled.

​
Testing Rate Limits in Development

If you want to test rate limiting in development mode, you can explicitly enable it by setting rateLimit.enabled to true: 
const config = createConfig({
  secondaryStorage: {
    enabled: true,
    rateLimit: {
      enabled: true,  // Force enable rate limiting in development
      page: {
        max: 40,
        window: 60
      },
      api: {
        max: 10,
        window: 20
      }
    }
  },
  // ... other config
})

​
Complete Example

Here’s a complete configuration example: 
const config = createConfig({
  name: "My SaaS App",
  description: "A powerful SaaS application",
  socials: {
    twitter: "https://x.com/mysaasapp",
    github: "https://github.com/mysaasapp"
  },
  payments: {
    advantages: {
      maxUsers: "number",
      premiumFeatures: "boolean",
      apiCalls: "number"
    },
    defaultProduct: {
      name: "Free",
      advantages: {
        maxUsers: 1,
        premiumFeatures: false,
        apiCalls: 100
      }
    },
    products: {
      pro: {
        productId: {
          production: "prod_xxxxx",
          development: "price_test_xxx"
        },
        name: "Pro",
        advantages: {
          maxUsers: 5,
          premiumFeatures: true,
          apiCalls: 1000
        }
      }
    }
  },
  auth: {
    magicLink: true,
    socialProviders: ["google", "github"]
  },
  secondaryStorage: {
    enabled: true,
    rateLimit: {
      page: { max: 50, window: 60 },
      api: { max: 20, window: 60 }
    }
  }
})