# Build-Time Feature Flags in OpenMAIC: Complete Configuration Guide

> Discover OpenMAIC build-time feature flags, controlling optional features via environment variables. Safely inline values for server and client bundles without exposing secrets.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: complete-guide
- Published: 2026-09-10

---

**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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/config/feature-flags.ts#L32))
- `isMaicEditorEnabled` – Lines 47-49, with fallback logic to the Pro workbench flag ([source](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/config/feature-flags.ts#L47))
- `isPlaybackRendererEnabled` – Lines 55-56 ([source](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/config/feature-flags.ts#L55))
- `isEditorRendererEnabled` – Lines 64-65 ([source](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/config/feature-flags.ts#L64))
- `isPiChatEnabled` – Lines 72-73 ([source](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/config/feature-flags.ts#L72))
- `shouldShowVocationalTestUi` – Lines 11-12 ([source](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/config/feature-flags.ts#L11))
- `isVideoExportEnabled` – Lines 21-22 ([source](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/config/feature-flags.ts#L21))
- `isPptxImportEnabled` – Lines 26-27 ([source](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/config/feature-flags.ts#L26))

Unit tests verifying the boolean parsing logic and fallback behavior are located in **[`tests/config/feature-flags.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/config/feature-flags.test.ts)**.

## Usage Examples

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

```typescript
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:

```typescript
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:

```typescript
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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/config/feature-flags.ts)**, with comprehensive tests in **[`tests/config/feature-flags.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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.