Skip to content
Features GitHub

Guidelines

Structure your project so every feature is found

A few conventions are all Features needs. Follow them and the CLI detects your features, their owners and their documentation automatically.

Two ways to declare a feature

A features folder, or a flag in a README

Both methods can be mixed in the same codebase. Folder names can use snake_case, camelCase or kebab-case.

Recommended

Method 1 · Features folder

every direct subfolder of features/ is a feature
src/
features/
saveUser/
components/
UserForm.ts
EmailInput.ts
utils/
useSaveUser.ts
useFetchUser.ts
transformUser.ts
README.md # helps for large features
feature-2/
...
components/ # common components used across features
utils/ # common utils/hooks used across features
Anywhere

Method 2 · Feature flag

any folder with feature: true in its README
services/
payments/ owner: backend-team
README.md # feature: true
stripe.go
shared/ # feature: false → skipped, children still scanned
notifications/
README.md # feature: true

feature: false skips a folder even inside features/. Unlike --ignore-path, its subfolders are still scanned, so nested features are still discovered.

Checklist

Must, should, may

Only the first two rules are required. The others unlock descriptions, ownership and decisions in the dashboard.

  1. MUST Create features in a features folder, or add feature: true to the README front matter. features/feature-1/
  2. MUST Put the code related to the feature inside the feature folder. feature-1/file.js
  3. SHOULD Add a README.md or README.mdx file into the feature folder. features/feature-1/README.md
  4. SHOULD Add a line of text describing the feature right after the README title. Handles user login and logout
  5. SHOULD Add front matter to the README with an owner property. owner: backend-team
  6. MAY Add any other properties you want to the front matter. figma: <url>
  7. MAY Add MADR decision records into the feature decisions folder. __docs__/decisions/001-use-jwt-tokens.md

README format

One README, all the metadata

Every front matter property is optional and you can add your own. The title overrides the folder name; the first line of text becomes the description.

---
feature: true # required if not in a `features` folder
owner: team_1
creation_date: 2022-01-01 # overrides the first commit date
status: active # active, deprecated, archived
deprecated: false
---

# Save user

Creates and updates user accounts from the profile page.
  • owner — the team shown in the dashboard and written to CODEOWNERS.
  • feature — true declares a feature anywhere, false skips one.
  • creation_date — overrides the date of the first commit in the feature.
  • status / deprecated — lifecycle of the feature: active, deprecated, archived.
Feature page in the Features dashboard showing the path, the owner, front matter properties as badges and the README description
The same README in the dashboard: owner, front matter properties as badges (URLs become links) and the rendered description.

Decision records

Keep decisions next to the code they shaped

Add Markdown files to a __docs__/decisions/ or .docs/decisions/ folder in the feature. They appear under the feature in the dashboard. The template is inspired by MADR.

  1. 01

    Title

    A clear, concise description of the decision

  2. 02

    Status

    proposed, accepted, rejected, deprecated or superseded

  3. 03

    Context

    Background and the problem being solved

  4. 04

    Decision

    What was decided

  5. 05

    Consequences

    Expected positive and negative outcomes

Decisions tab of a feature in the Features dashboard listing its decision records
Decision records listed in the Decisions tab of the feature.

Feature metadata annotations

Tag flags and dependencies from any file

Special comments attach metadata to a feature from anywhere in the codebase. The metadata key becomes a tab in the web UI, and properties are free-form key-value pairs.

--feature-<metadata-key> feature:<feature-folder-basename>, property: value, ...

feature: is optional when the comment is already inside the feature folder.

TypeScript
// --feature-flag feature: feature-1, name: feature-flag1, type: experiment, owner: team-a, introduced_on: 2025-01-01

export function experimentalLoginFlow() {
  // implementation
}
Python
# --feature-flag name: feature-flag1, type: processing, language: python
Rust
// --feature-flag name: feature-flag1, type: core, status: stable
Bash
# --feature-flag name: feature-flag1, environment: production, region: us-west-2
Flag tab of a feature in the Features dashboard: a table of feature flags with their name, type and status
A --feature-flag annotation becomes a Flag tab, with one column per property.

Read the full guidelines and README format on GitHub.

See your features in one command

No configuration, no account. Point the CLI at a folder and open the dashboard.

$ npx features-cli@latest serve ./src
Open the live demo Star on GitHub