Definitions in depth
Environments
Environments give one feature different rules in each place it runs, such as staging and production, and build a datafile for each. They are optional. The default project has none, and every feature has one list of rules.
Environments, sets or neither#
Start with neither unless you know you need more:
- Neither is the default. Each feature has one list of rules and the project builds one set of datafiles. Test changes before they merge, and use a percentage rollout in production.
- Environments keep the rules for staging and production side by side in each feature file. Choose them when one change should be reviewed for all environments at once.
- Sets keep a separate tree of definitions per release lane, and changes move from one lane to the next through promotions. Choose them when a lane should be able to differ completely, as described below.
The choice can change later. convert moves a project between the three, and checks that every feature and global variable builds the same.
Add environments#
For a new project, start from the example with environments in an empty directory:
npx @featurevisor/cli@latest init --example=with-environmentsFor an existing project, convert it. Converting lists the environments in the configuration and rewrites your definitions to match:
module.exports = { environments: ['staging', 'production'],}Leave environments out entirely for a project without them. An empty list fails.
Give each environment its own rules#
With environments, rules groups its rule lists by environment. This keeps checkout from the Quick start as it is in production, and fully on in staging:
description: Checkout redesignbucketBy: userIdrules: staging: - key: everyone conditions: "*" percentage: 100 production: - key: netherlands conditions: netherlands percentage: 100 - key: everyone conditions: "*" percentage: 25- A feature that leaves out an environment has no rules there, so it is disabled, though
forceentries for that environment still apply. An empty list such asstaging: []says the same, unless the environment inherits. - A feature may leave out
rulesaltogether, and then has no rules in any environment. forceandexposeare grouped by environment the same way, and so are a global variable'soverrides.- Attributes, segments, schemas and targets are shared by every environment.
Build a datafile per environment#
Building writes each target's datafile once per environment:
tree datafilesdatafiles├── REVISION├── production│ └── featurevisor-all.json└── staging └── featurevisor-all.jsonbuild --environment=staging builds only staging and leaves production untouched, but still moves the shared revision forward. Build every environment before you publish the whole datafiles directory.
Load the right datafile#
Each deployment of your application loads its own environment's file, such as production/featurevisor-all.json. The SDK evaluates whatever datafile it is given, and never picks an environment from the context.

Test and evaluate per environment#
Every feature assertion names its environment:
feature: checkoutassertions: - description: Dutch users, production environment: production at: 90 context: country: nl expectedToBeEnabled: true - description: Everyone, staging environment: staging at: 90 context: country: de expectedToBeEnabled: trueThe CLI's runtime commands take the same choice, such as npx featurevisor evaluate --environment=production. See Testing and the CLI.
Add an environment later#
A project that has grown can gain an environment without anyone touching their definitions. List it, and say which environment it follows wherever a definition says nothing:
module.exports = { environments: ['dev', 'staging', 'production'], inheritEnvironments: { dev: { from: 'staging' }, },}Lint and tests pass as they did, and the staging and production datafiles stay the same apart from the revision. Each target gains a dev datafile, which matches its staging one until a team writes something for dev.
Without inheritEnvironments, every feature starts disabled in dev. A team that gives its feature rules in dev then finds it still disabled if it depends on a feature nobody else has touched, and a global variable tied to such a feature returns its disabled value.
Each definition decides for itself:
What a definition says for dev | What happens in dev |
|---|---|
| Nothing | It uses what it has for staging |
dev: [] | It has none, and inherits nothing |
dev: with entries | It uses its own |
This gives checkout a rule of its own in dev. Only this file changes, so only its owners review it:
# ...rules: dev: - key: netherlands conditions: netherlands percentage: 100 staging: - key: everyone conditions: "*" percentage: 100 production: - key: netherlands conditions: netherlands percentage: 100 - key: everyone conditions: "*" percentage: 25rules,force,exposeand a global variable'soverrideseach inherit on their own, so this feature still uses anyforceentries staging has. Writeforce: { dev: [] }to stop that, orexpose: { dev: true }to expose indevwhat staging does not.- A list replaces the inherited one whole. Nothing is merged.
- A feature inheriting its rules gives each user the variation it gives them in the other environment, as State files explains.
- Test assertions do not inherit. Add one that names
devwhen you wantdevchecked. - An edit to staging reaches
devat the next build, whichdiffpoints out. - Several environments may inherit from one, as long as that one inherits from nothing.
Production can inherit too
If production inherits from staging, every edit to staging reaches production at the next build. Requiring production refuses this.
To see who has written their own rules for dev, and who still has none:
npx featurevisor list --features --defined-in=devnpx featurevisor list --features --not-defined-in=devBoth also work with --variables, where they read overrides.
Roll out the new environment#
Adding dev to the configuration changes no application. Three steps make it live:
- Build it in your deployment. A plain
npx featurevisor buildwrites every environment. A script that names each one, such as--environment=staging, needs a line fordev. - Commit its state file. The first build writes
.featurevisor/existing-state-dev.json, whichgit add .featurevisorin Deployment picks up. A workflow that names each file has to add it. Without it,devstill follows staging, but users can switch variations the first time a team writes rules of its own. - Point applications at it. Each deployment running in
devloadsdev/featurevisor-all.json, as Load the right datafile shows. Nothing changes for an application until it does.
Check an existing environment#
A new dev has nothing relying on it. If dev already exists, a definition that leaves it out is off there today, and a team may depend on that. inheritEnvironments turns that definition on in dev without anyone editing its file. Lint has nothing to report, since nothing is invalid, and diff shows only the change to the configuration.
List what would change before you add the setting:
npx featurevisor list --features --not-defined-in=devnpx featurevisor list --variables --not-defined-in=devWrite dev: [] in each definition that must stay as it is in dev, then add the setting. These lists read rules and overrides. A feature's force and expose inherit too, so check any feature that has them.
Require an environment#
Leaving out an environment passes lint, so a feature that forgets production ships disabled there. To make that a choice someone has to write down, list the environment:
module.exports = { environments: ['staging', 'production'], requireRulesIn: ['production'], requireOverridesIn: ['production'],}requireRulesIn applies to each feature's rules, and requireOverridesIn to each global variable's overrides. A definition that writes nothing for production fails lint:
features/checkout.yml => Error: Missing rules for required environment "production". Add them, or write "production: []" to keep the feature off there. Path: rules.productionproduction: [] satisfies the rule, because writing it is the decision. Archived definitions are exempt. An environment that inherits cannot be required, and the configuration fails if you try.
Switch an existing project#
convert changes an existing project's shape, rewriting every definition, test spec, state file and the configuration to match. Give a project without environments staging and production:
npx featurevisor convert --to=environmentsIt previews by default, and writes only with --apply. Before writing, it checks that a converted copy lints, passes its tests and builds every feature and global variable the same in each environment.
To remove environments, name the one whose behaviour to keep:
npx featurevisor convert --to=flat --keep=productionAfter applying, add or remove --environment in your commands, and point applications at the datafile paths the preview names. Converting shows what each conversion writes and checks.
Older scaffolds also used tag: all in targets/all.yml. Keep it to include only tagged definitions, or remove it to include everything. Target selection does not depend on environments.
Release lanes with sets#
Some teams treat dev, staging and production as separate release lanes rather than environments of one definition. Each lane is a set with its own complete tree, so a feature can differ completely between lanes, and changes move forward only when promoted. The example for this layout keeps its historical name:
npx @featurevisor/cli@latest init --example=environmentsIt enables sets instead of environments, and uses promotionFlows to keep promotions moving forward one lane at a time:
module.exports = { sets: true, promotionFlows: [ { from: 'dev', to: 'staging' }, { from: 'staging', to: 'production' }, ],}Each lane has its own attributes/, segments/, features/, targets/ and tests/ under sets/<lane>/. Rules are plain lists, because there are no environments. The same feature can be fully on in dev and still off in production:
description: New checkout flowbucketBy: userIdrules: - key: everyone conditions: "*" percentage: 100description: New checkout flowbucketBy: userIdrules: - key: everyone conditions: "*" percentage: 0Building writes datafiles/dev/featurevisor-all.json, datafiles/staging/featurevisor-all.json and datafiles/production/featurevisor-all.json. When dev is ready, promote it to staging:
npx featurevisor promote --from=dev --to=staging --applypromotionFlows rejects promoting straight from dev to production. See Sets and Promotions.
In the example, staging sits between the two: its checkoutFlow is on for the internal segment and off for everyone else.

Turn environments into sets#
To make an existing project's environments release lanes, convert it:
npx featurevisor convert --to=setsEach environment becomes a set, and each feature keeps that environment's rules there. convert --to=environments goes back, when the sets share their attributes, segments, schemas and targets. See Turn environments into sets and Go back to environments.

