Featurevisor

Ship it

Building datafiles

featurevisor build turns your definitions into datafiles: one JSON file per target, and per environment if you have them. Your applications load these files into an SDK, so publishing new datafiles is how a change reaches users, without a release of the application.

Build

Command
npx featurevisor build

The default project has one target, all, which includes everything:

targets/all.yml
description: All features and global variables

So the build writes one datafile:

Output
Building Featurevisor datafiles
  Current revision: 0
  Target: all
    ✔ datafiles/featurevisor-all.json
Datafiles built
Latest revision: 1

Next to it, datafiles/REVISION holds the new revision. The build also updates the state files in .featurevisor/, which you commit. In CI, build after lint and test pass, then deploy the datafiles directory.

Run lint and tests first. build checks only what it needs to write datafiles, such as dependency cycles, so a successful build does not mean the project is valid. A rule that still uses the removed segments field, for example, builds without it and then matches nobody. The feature is switched off for that audience, and only lint reports why.

What a datafile contains

A datafile holds what an SDK needs to evaluate, and nothing it can do without:

  • the features and global variables the target selects, plus any they depend on
  • the segments their conditions reference, including references through other segments
  • percentages as whole numbers out of 100,000, so 25% is 25000
  • condition expressions as strings by default (see stringify)
  • a revision, a schemaVersion and the featurevisorVersion that built it

Attributes, schemas, descriptions and tests stay in the project. How it works shows a datafile for checkout.

Treat a datafile as public. A browser or app that loads it can read every key and value inside, so a feature named after an unannounced product can be seen before its launch. Targets explains what reaches each application.

Choose what to build

Build only some targets with --target, once or more:

Command
npx featurevisor build --target=web --target=mobile

With environments, a plain build writes every environment. --environment=staging builds only staging, and leaves the other environments' files at their previous revision while the shared revision still moves forward. Build every environment before you publish the whole datafiles directory. Unknown environment names are rejected before anything is written, and --environment is rejected in a project without environments.

Revisions

Every build increments the revision in .featurevisor/REVISION, and writes it into each datafile and datafiles/REVISION. An application can compare revisions to tell whether a newer datafile has arrived.

Set your own revision, such as a release or commit identifier:

Command
npx featurevisor build --revision=1.2.3

Or derive each datafile's revision from a hash of its content, so a file that did not change keeps its revision and its cache:

Command
npx featurevisor build --revision-from-hash

To build without touching the state files, for example in a preview job:

Command
npx featurevisor build --no-state-files

Add --json to print a datafile instead of writing it, and --pretty to indent it. Narrow it to one feature and what it needs:

Command
npx featurevisor build \
  --feature=showCookieBanner \
  --json \
  --pretty

Print everything, one target, or one global variable after defining supportEmail:

Commands
npx featurevisor build --json --pretty
npx featurevisor build --target=all --json --pretty
npx featurevisor build --variable=supportEmail --json --pretty

Printing never changes the project's revision. A printed datafile uses the revision tester unless you pass --revision. With environments, add --environment to choose which one, and pass at most one --target, since only one datafile is printed. SDK authors can feed this output to a test runner.

Change the output directory

Datafiles go to datafiles/, or to datafilesDirectoryPath if you set it. --datafiles-dir overrides it for one build, and creates the directory if needed. The datafiles and their REVISION go there, while state files stay where they are.

For a one off export that leaves the project's state alone:

Command
npx featurevisor build \
  --datafiles-dir=./custom-directory \
  --no-state-files
Previous
Linting
Next
State files