Build-Time Feature Flags in OpenMAIC: Complete Configuration Guide

OpenMAIC controls optional functionality through eight build-time feature flags that read from NEXT_PUBLIC_* environment variables, allowing Next.js to inline values safely for both server and client bundles without exposing secrets.

The OpenMAIC repository uses a centralized feature-flag system to gate experimental UI components, premium workbenches, and rendering pipelines. These flags are evaluated at build time in lib/config/feature-flags.ts, ensuring that disabled features are completely excluded from the production bundle.

How Build-Time Feature Flags Work in OpenMAIC

OpenMAIC leverages Next.js public environment variables to create build-time feature flags. Any environment variable prefixed with NEXT_PUBLIC_ is automatically inlined into the JavaScript bundle during the build process. This mechanism allows client-side code to check feature availability without exposing server-only secrets or requiring runtime API calls.

Each flag is implemented as a simple boolean function that reads its corresponding environment variable through a readBoolean helper. Because the values are determined at build time, they cannot be toggled at runtime without redeploying the application.

Complete List of Build-Time Feature Flags

The following public feature flags are defined in lib/config/feature-flags.ts:

Flag Function	Environment Variable	Default	Description
isProWorkbenchEnabled()	NEXT_PUBLIC_PRO_WORKBENCH_ENABLED	OFF	Enables the Pro workbench UI. Both server-side routes and client components require this flag to be true before the workbench page is reachable.
isMaicEditorEnabled()	NEXT_PUBLIC_MAIC_EDITOR_ENABLED (fallback to NEXT_PUBLIC_PRO_WORKBENCH_ENABLED)	OFF	Toggles the MAIC editor (Pro mode). If the Pro workbench flag is true, the editor is automatically enabled.
isPlaybackRendererEnabled()	NEXT_PUBLIC_MAIC_PLAYBACK_RENDERER_ENABLED	OFF	Switches the classroom playback to the experimental canvas renderer.
isEditorRendererEnabled()	NEXT_PUBLIC_MAIC_EDITOR_RENDERER_ENABLED	OFF	Switches the slide editor to the experimental canvas renderer.
isPiChatEnabled()	NEXT_PUBLIC_PI_CHAT_ENABLED	OFF	Activates the experimental Pi-based classroom chat runtime (client-side and corresponding server routes).
shouldShowVocationalTestUi()	NEXT_PUBLIC_SHOW_VOCATIONAL_TEST_UI	OFF	Shows a UI toggle for testing the vocational task-engine feature (does not affect routing).
isVideoExportEnabled()	NEXT_PUBLIC_ENABLE_VIDEO_EXPORT	OFF	Reveals the "Export Video" entry in the export menu. The underlying rendering pipeline is always present; this flag only hides the UI affordance.
isPptxImportEnabled()	NEXT_PUBLIC_ENABLE_PPTX_IMPORT	OFF	Exposes the experimental PPTX import entry point.

All default values are OFF (falsy), meaning features must be explicitly enabled via environment variables before building.

Source Code Implementation

The authoritative implementation resides in lib/config/feature-flags.ts. Each function wraps a readBoolean utility that normalizes environment variable strings into strict boolean values.

Specific implementations include:

• isProWorkbenchEnabled – Lines 32-34 (source)
• isMaicEditorEnabled – Lines 47-49, with fallback logic to the Pro workbench flag (source)
• isPlaybackRendererEnabled – Lines 55-56 (source)
• isEditorRendererEnabled – Lines 64-65 (source)
• isPiChatEnabled – Lines 72-73 (source)
• shouldShowVocationalTestUi – Lines 11-12 (source)
• isVideoExportEnabled – Lines 21-22 (source)
• isPptxImportEnabled – Lines 26-27 (source)

Unit tests verifying the boolean parsing logic and fallback behavior are located in tests/config/feature-flags.test.ts.

Usage Examples

Conditionally render the Pro workbench UI based on the build-time flag:

import { isProWorkbenchEnabled } from '@/lib/config/feature-flags';

if (isProWorkbenchEnabled()) {
  // Initialize Pro workbench features
  router.registerProRoutes();
}

Switch between experimental and legacy renderers using the playback flag:

import { isPlaybackRendererEnabled } from '@/lib/config/feature-flags';

const renderer = isPlaybackRendererEnabled()
  ? new ExperimentalCanvasRenderer()
  : new LegacyRenderer();

Hide menu items for features that are not enabled at build time:

import { isVideoExportEnabled } from '@/lib/config/feature-flags';

export const ExportMenuItem = () =>
  isVideoExportEnabled() ? <MenuItem label="Export Video" /> : null;

Summary

• OpenMAIC uses eight build-time feature flags prefixed with NEXT_PUBLIC_ to control experimental and premium functionality.
• Flags are evaluated at build time and inlined into the bundle, making them safe for client-side use without exposing secrets.
• The central implementation lives in lib/config/feature-flags.ts, with comprehensive tests in tests/config/feature-flags.test.ts.
• All flags default to OFF, requiring explicit environment variable configuration before deployment.
• The isMaicEditorEnabled() function includes a fallback mechanism that automatically enables the editor if NEXT_PUBLIC_PRO_WORKBENCH_ENABLED is true.

Frequently Asked Questions

How do I enable the Pro workbench in OpenMAIC?

Set the environment variable NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true in your .env.local or build environment before running next build. This flag must be enabled for both the server and client bundles to access the Pro workbench routes and UI components.

Are build-time feature flags secure for sensitive configuration?

No. Because NEXT_PUBLIC_* variables are inlined into the client-side JavaScript bundle, they are visible to anyone who inspects the browser source. Use these flags only for feature gating, never for API keys, database credentials, or other secrets. The OpenMAIC source code specifically uses these for UI toggles and experimental renderers that do not require sensitive data.

What happens if I change a feature flag after deployment?

Build-time feature flags are frozen at compile time. Changing an environment variable after the Next.js build completes has no effect on the running application. You must trigger a new build and redeploy for flag changes to take effect, ensuring predictable feature states across server and client contexts.

Where can I find the unit tests for these feature flags?

The test suite is located in tests/config/feature-flags.test.ts. These tests verify that the boolean parsing logic correctly handles string values like "true", "false", "1", and "0", and that the fallback behavior for isMaicEditorEnabled() properly respects the Pro workbench flag when the editor-specific variable is unset.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}