Quick start

Prerequisites#

• Node.js >= 24.0.0

Initialize your project#

Run the following command to initialize your project:

$ npx @featurevisor/cli init

This is meant to be a completely separate repository from your application code. Learn more in Projects page.

Installation#

Once your project has been initialized, install all the dependencies:

$ npm install

Configure your project#

Featurevisor's project configuration is stored in featurevisor.config.js file, with minimum configuration looking like this:

module.exports = {
  tags: [
    'all',
  ],
  environments: [
    'staging',
    'production'
  ],
};

Learn more in Configuration.

By default, Featurevisor defines attributes, segments, and features as YAML files. If you want JSON, TOML, or any other format, see custom parsers guide.

Create an attribute#

Attributes are the building blocks of creating conditions.

We will start by creating an attribute called userId:

description: User ID
type: string

Learn more in Attributes.

Create a segment#

Segments are reusable conditions that can be applied as rules in your features to target specific users or groups of users.

Let's create a new attribute called country first:

description: Country
type: string

Now, let's create a segment called germany:

description: Users from Germany
conditions:
  - attribute: country
    operator: equals
    value: de

Learn more in Segments.

Create a feature#

We have come to the most interesting part now.

We can create a new showBanner feature, that controls showing a banner on our website:

description: Show banner
tags:
  - all
# this makes sure the same User ID consistently gets the same experience
bucketBy: userId
rules:
  # staging rules
  staging:
    - key: everyone     # unique key for this rule
      segments: '*'     # targeting everyone
      percentage: 100   # rolled out to 100% of the traffic
  # production rules
  production:
    - key: de
      segments: germany # rolling out to Germany first
      percentage: 100
    - key: everyone
      segments: '*'     # everyone
      percentage: 0     # disabled for everyone else

Learn more in Features for complex setups involving variations and variables.

Create a target#

Targets decide the datafiles (pure JSON files that SDKs consume) that get built.

The init command already created a default all target for you:

description: All features
tag: all

This target selects every feature tagged with all, and builds a featurevisor-all.json datafile in datafiles/ directory.

Learn more in Targets and Building datafiles.

Linting#

We can lint the content of all our definitions to make sure they are all valid:

$ npx featurevisor lint

Learn more in Linting.

Build datafiles#

Datafiles are static JSON files that we expect our client-side applications to consume using the Featurevisor SDKs.

Now that we have all the definitions in place, we can build the project:

$ npx featurevisor build

This will generate datafiles in the datafiles directory for each of your targets against each environment as defined in your featurevisor.config.js file.

With our example, we will have the following datafiles generated:

datafiles/
├── staging/
│   └── featurevisor-all.json
└── production/
  └── featurevisor-all.json

Learn more in Building datafiles.

Deploy datafiles#

This is the part where you deploy the datafiles to your CDN or any custom server.

Once done, the URLs of the datafiles may look like https://cdn.yoursite.com/production/featurevisor-all.json.

Learn more in Deployment.

Consume datafiles using the SDK#

Now that we have the datafiles deployed, we can consume them using Featurevisor SDKs.

Install SDK#

In your application, install the Featurevisor SDK first:

$ npm install --save @featurevisor/sdk

Featurevisor JavaScript SDK is compatible with both Node.js and browser environments.

Find more SDKs in other languages here.

Initialize SDK#

You can initialize the SDK as follows:

import { createFeaturevisor } from '@featurevisor/sdk'
const datafileUrl =
  'https://cdn.yoursite.com/production/featurevisor-all.json'
const datafileContent = await fetch(datafileUrl)
  .then((res) => res.json())
const f = createFeaturevisor({
  datafile: datafileContent,
})

Set context#

Let the SDK know against what context the values should be evaluated:

const context = {
  userId: '123',
  country: 'de',
}
f.setContext(context)

Evaluate values#

Once the SDK is initialized, you can evaluate your features:

// flag status: true or false
const isBannerEnabled = f.isEnabled('showBanner')

Featurevisor SDK will take care of evaluating the right value(s) for you synchronously against the provided userId and country attributes in the context.

Variables & Variations#

Above example only makes use of the feature's boolean flag status only, but features may also contain variables and variations, which can be evaluated with the SDK instance:

// variation: `control`, `treatment`, or more
const bannerVariation = f.getVariation('showBanner', context)
// variables
const variableKey = 'myVariableKey'
const myVariable = f.getVariable('showBanner', variableKey, context)

Find more examples of SDK usage here.

Further reading#

• Attributes
• Segments
• Features
• Targets
• Linting
• Testing
• Building datafiles
• Deployment
• SDKs