Feature Flags Configuration in the Next.js Supabase SaaS Kit

Enable or disable team accounts, billing, notifications, and theme toggling in the Next.js Supabase SaaS Kit using feature flags.

The feature flags configuration at apps/web/config/feature-flags.config.ts controls which features are enabled in your application. Toggle team accounts, billing, notifications, and more using environment variables.

Feature Flags vs Configuration

Feature flags control whether functionality is available to users. Use them to ship different product tiers, run A/B tests, or disable features during maintenance. Unlike configuration, feature flags are meant to change at runtime or between deployments.

Defaults Note

The "Default" column shows what the code uses if the environment variable is not set. The kit's .env file ships with different values to demonstrate features. Check your .env file for the actual starting values.

Available Feature Flags

Flag	Environment Variable	Default	Description
Theme Toggle	`NEXT_PUBLIC_ENABLE_THEME_TOGGLE`	`true`	Allow users to switch themes
Account Deletion	`NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_DELETION`	`false`	Users can delete their accounts
Team Accounts	`NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS`	`true`	Enable team/organization features
Team Creation	`NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_CREATION`	`true`	Users can create new teams
Team Deletion	`NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_DELETION`	`false`	Users can delete their teams
Personal Billing	`NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_BILLING`	`false`	Billing for personal accounts
Team Billing	`NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_BILLING`	`false`	Billing for team accounts
Notifications	`NEXT_PUBLIC_ENABLE_NOTIFICATIONS`	`true`	In-app notification system
Realtime Notifications	`NEXT_PUBLIC_REALTIME_NOTIFICATIONS`	`false`	Live notification updates
Version Updater	`NEXT_PUBLIC_ENABLE_VERSION_UPDATER`	`false`	Check for app updates
Language Priority	`NEXT_PUBLIC_LANGUAGE_PRIORITY`	`application`	User vs app language preference

Common Configurations

B2C SaaS (Personal Accounts Only)

For consumer applications where each user has their own account and subscription:

NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS=false
NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_BILLING=true
NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_DELETION=true

B2B SaaS (Team Accounts Only)

For business applications where organizations subscribe and manage team members:

NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS=true
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_BILLING=true
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_DELETION=true
NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_BILLING=false

Hybrid Model (Both Personal and Team)

For applications supporting both individual users and teams (uncommon):

NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS=true
NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_BILLING=true
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_BILLING=true

Managed Onboarding (No Self-Service Team Creation)

For applications where you create teams on behalf of customers:

NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS=true
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_CREATION=false
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_BILLING=true

Decision Matrix

Use this matrix to decide which flags to enable:

Use Case	Theme	Teams	Team Creation	Personal Billing	Team Billing	Deletion
B2C Consumer App	Yes	No	-	Yes	-	Yes
B2B Team SaaS	Optional	Yes	Yes	No	Yes	Optional
Enterprise SaaS	Optional	Yes	No	No	Yes	No
Freemium Personal	Yes	No	-	Yes	-	Yes
Marketplace	Optional	Yes	Yes	Yes	No	Yes

How It Works

The configuration file parses environment variables with sensible defaults:

const featuresFlagConfig = FeatureFlagsSchema.parse({
  enableThemeToggle: getBoolean(
    process.env.NEXT_PUBLIC_ENABLE_THEME_TOGGLE,
    true,
  ),
  enableAccountDeletion: getBoolean(
    process.env.NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_DELETION,
    false,
  ),
  enableTeamDeletion: getBoolean(
    process.env.NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_DELETION,
    false,
  ),
  enableTeamAccounts: getBoolean(
    process.env.NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS,
    true,
  ),
  enableTeamCreation: getBoolean(
    process.env.NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_CREATION,
    true,
  ),
  enablePersonalAccountBilling: getBoolean(
    process.env.NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_BILLING,
    false,
  ),
  enableTeamAccountBilling: getBoolean(
    process.env.NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_BILLING,
    false,
  ),
  languagePriority: process.env.NEXT_PUBLIC_LANGUAGE_PRIORITY,
  enableNotifications: getBoolean(
    process.env.NEXT_PUBLIC_ENABLE_NOTIFICATIONS,
    true,
  ),
  realtimeNotifications: getBoolean(
    process.env.NEXT_PUBLIC_REALTIME_NOTIFICATIONS,
    false,
  ),
  enableVersionUpdater: getBoolean(
    process.env.NEXT_PUBLIC_ENABLE_VERSION_UPDATER,
    false,
  ),
});

Using Feature Flags in Code

In Server Components

import featureFlagsConfig from '~/config/feature-flags.config';
export default function SettingsPage() {
  return (
    <div>
      {featureFlagsConfig.enableTeamAccounts && (
        <TeamAccountsSection />
      )}
      {featureFlagsConfig.enableAccountDeletion && (
        <DeleteAccountButton />
      )}
    </div>
  );
}

In Client Components

'use client';
import featureFlagsConfig from '~/config/feature-flags.config';
export function ThemeToggle() {
  if (!featureFlagsConfig.enableThemeToggle) {
    return null;
  }
  return <ThemeSwitch />;
}

The navigation configuration files already use feature flags:

// From personal-account-navigation.config.tsx
featureFlagsConfig.enablePersonalAccountBilling
  ? {
      label: 'common:routes.billing',
      path: pathsConfig.app.personalAccountBilling,
      Icon: <CreditCard className={iconClasses} />,
    }
  : undefined,

Feature Flag Details

Theme Toggle

Controls whether users can switch between light and dark themes. When disabled, the app uses NEXT_PUBLIC_DEFAULT_THEME_MODE exclusively.

Account Deletion

Allows users to permanently delete their personal accounts. Disabled by default to prevent accidental data loss. Consider enabling for GDPR compliance.

Team Accounts

Master switch for all team functionality. When disabled, the application operates in personal-account-only mode. Disabling this also hides team-related navigation and features.

Team Creation

Controls whether users can create new teams. Set to false for enterprise scenarios where you provision teams manually.

Team Deletion

Allows team owners to delete their teams. Disabled by default to prevent accidental data loss.

Personal vs Team Billing

Choose one based on your business model:

Personal billing: Each user subscribes individually (B2C)
Team billing: Organizations subscribe and add team members (B2B)

Enabling both is possible but uncommon. Most SaaS applications use one model.

Notifications

Enables the in-app notification system. When combined with realtimeNotifications, notifications appear instantly via Supabase Realtime.

Language Priority

Controls language selection behavior:

application: Use the app's default locale
user: Respect the user's browser language preference

Version Updater

When enabled, the app checks for updates and notifies users. Useful for deployed applications that receive frequent updates.

Common Pitfalls

Enabling both billing modes: While technically possible, enabling both personal and team billing may create confusing user experience (unless your business model is a hybrid of both). Choose one model.
Disabling teams after launch: If you've collected team data and then disable teams, users lose access. Plan your model before launch.
Forgetting deletion flows: If you enable deletion, ensure you also handle cascading data deletion and GDPR compliance.
Realtime without base notifications: realtimeNotifications requires enableNotifications to be true. The realtime flag adds live updates, not the notification system itself.

Application Configuration - Core app settings
Environment Variables - Complete variable reference
Navigation Configuration - Sidebar customization