Feature Flags

Enable and disable Nebutra-Sailor product features per environment using environment-variable-based feature flags.

How feature flags work

Nebutra-Sailor uses environment-variable-based feature flags to enable or disable entire product features without changing code or redeploying. Each flag is a boolean string (true / false) read at startup by @nebutra/config.

All flags default to false when the variable is absent. Setting a flag to true activates the associated routes, UI, and background jobs.

Available flags

FlagDefaultEffect
FEATURE_AI_CHATfalseEnables the AI chat endpoints on the API gateway and the chat UI in the dashboard. Requires OPENAI_API_KEY or OPENROUTER_API_KEY.
FEATURE_AI_EMBEDDINGSfalseEnables the embeddings API. Requires OPENAI_API_KEY.
FEATURE_BLOGfalseEnables the Sanity-powered blog on the landing page. Requires Sanity Studio to be configured.
FEATURE_CHANGELOGfalseEnables the public changelog page on the landing page.
FEATURE_TEAMSfalseEnables team and organization features: inviting members, role management, and per-org billing.
FEATURE_ANALYTICSfalseEnables PostHog event tracking. Requires NEXT_PUBLIC_POSTHOG_KEY.

Enabling flags per environment

Add the flag to your .env.local:

FEATURE_AI_CHAT=true
FEATURE_TEAMS=true

In the Vercel dashboard, open Settings → Environment Variables. Add the flag for the Preview environment only. This lets you test a feature on a preview URL before promoting it to production.

Same as above, but select the Production environment. Only enable flags that are fully ready for end users.

Flag dependencies

Some flags require additional environment variables to be functional:

Runtime feature flags via Edge Config

The environment-variable flags above are evaluated at build time (for Next.js static generation) and at process startup. For flags that need to change without a redeployment, use Vercel Edge Config.

Edge Config gives you sub-millisecond read latency at the edge — ideal for feature flags that need to change without a redeploy.

Setup

  1. Create an Edge Config store in the Vercel dashboard (Storage → Edge Config → Create).
  2. Link it to your project and run vercel env pull to get EDGE_CONFIG locally.
  3. Install the client:
pnpm add @vercel/edge-config

Writing flags (server-side or deploy hook)

// scripts/update-flags.ts — run via CI or a Vercel deploy hook
import { createClient } from "@vercel/edge-config";

const edgeConfig = createClient(process.env.EDGE_CONFIG!);
await edgeConfig.set("featureFlags", {
  FEATURE_AI_CHAT: true,
  FEATURE_BETA_DASHBOARD: false,
});

Reading flags at the edge (middleware / proxy.ts)

import { get } from "@vercel/edge-config";

export async function middleware() {
  const flags = await get<Record<string, boolean>>("featureFlags");
  const aiChatEnabled = flags?.FEATURE_AI_CHAT ?? false;
  // use aiChatEnabled to conditionally rewrite/redirect
}

Reading flags in Server Components

import { get } from "@vercel/edge-config";

export default async function Page() {
  const flags = await get<Record<string, boolean>>("featureFlags") ?? {};
  if (!flags.FEATURE_BETA_DASHBOARD) notFound();
  return <BetaDashboard />;
}

Edge Config reads are cached per-request, so calling get() multiple times in a single render is free.

Per-tenant feature flags (planned)

Future versions of Nebutra-Sailor will support per-tenant feature flags tied to the customer's subscription plan:

PlanFlags automatically enabled
FreeFEATURE_CHANGELOG, FEATURE_BLOG
Pro+ FEATURE_AI_CHAT, FEATURE_ANALYTICS
Enterprise+ FEATURE_AI_EMBEDDINGS, FEATURE_TEAMS

Per-tenant feature flags are on the roadmap and not yet implemented. The current system applies flags globally. Until per-tenant flags ship, you can approximate per-plan feature gating using the @nebutra/permissions RBAC system — check tenant.plan in your permission policies and return 403 for features the plan doesn't include.

Configuration Overview

How config validation works and where to set variables per environment.

Environment Variables

Full reference for all environment variables including AI and analytics keys.

AI Integration

Setting up AI chat and embeddings features.

Deployment

Managing feature flags in Vercel preview and production environments.

How is this guide?

Edit on GitHub

Last updated on

On this page

How feature flags work
Available flags
Enabling flags per environment
Flag dependencies
Runtime feature flags via Edge Config
Setup
Writing flags (server-side or deploy hook)
Reading flags at the edge (middleware / proxy.ts)
Reading flags in Server Components
Per-tenant feature flags (planned)
Related