# Webiny Add Feature Flag

Adding a new feature flag to the Webiny system.

- Repository: https://github.com/webiny/webiny-js (8051 stars)
- Category: Engineering
- License: see repository
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add webiny/webiny-js --skill webiny-add-feature-flag -g -a claude-code -y`
Codex: `npx skills add webiny/webiny-js --skill webiny-add-feature-flag -g -a codex -y`
Cursor: `npx skills add webiny/webiny-js --skill webiny-add-feature-flag -g -a cursor -y`
Gemini CLI: `npx skills add webiny/webiny-js --skill webiny-add-feature-flag -g -a gemini-cli -y`

## Description

Adding a new feature flag to the Webiny system. Use this skill when creating a new feature flag (simple boolean or nested group), gating a feature at the config/admin/API level, or wiring a flag into the WCP license system. Covers IFeatureFlagsDto, KnownFeatureFlag, Zod schema, FeatureFlag.CanUse components, useFeatureFlags().isEnabled(), the API FeatureFlags abstraction, toDto(), and the LICENSE_CHECKS decorator pattern.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Adding a New Feature Flag

A WCP license is required for feature flags to work. The license is the gate; the config is the switch within the gate.

## Decision Flow

```
1. No license at all             → false (everything off, config ignored)
2. License blocks the flag       → false (config ignored)
3. License allows + config=false → false (config can disable what license allows)
4. License allows + config=true  → true
5. License allows + config unset → true  (license is the authority for unset flags)
6. Not in LICENSE_CHECKS + license exists + config unset → true
7. Not in LICENSE_CHECKS + license exists + config=false → false
```

Key points:

- Config can **disable** what the license allows, but cannot **enable** what the license blocks.
- Flags not governed by a license (`LICENSE_CHECKS`) still require a license to exist, then config decides.
- Without any license, all flags are off regardless of config.

## Architecture

- **`FeatureFlags` class** (`packages/feature-flags/src/FeatureFlags.ts`), single `isEnabled(name)` method resolves dot-path strings against the DTO. Flags are disabled by default (`undefined → false`). Also provides `isExplicitlyDisabled(name)` to distinguish "not set" from "set to false".
- **`IFeatureFlagsDto`** (`packages/feature-flags/src/types.ts`), the typed DTO interface.
- **`KnownFeatureFlag`** (`packages/feature-flags/src/FeatureFlags.ts`), string literal union for autocomplete.
- **Zod schema** (`packages/project/src/extensions/FeatureFlags.tsx`), validates the config input.
- **`toDto()`** returns the fully resolved state (all flags explicitly set), used by the `featureFlags` GraphQL query.
- **License decorators** intercept `isEnabled()` and apply the decision flow above via a `LICENSE_CHECKS` map.

## Steps to Add a Simple Boolean Flag

### 1. Add to DTO type

**File:** `packages/feature-flags/src/types.ts`

Add the new flag to `IFeatureFlagsDto`:

The rest: https://github.com/webiny/webiny-js/blob/HEAD/skills/repo-skills/add-feature-flag/SKILL.md