Quick start

Prerequisites#

• Node.js >= 20.0.0

Initialize your project#

Run the following command to initialize your project:

$ mkdir my-featurevisor-project && cd my-featurevisor-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 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:

type: string
description: User ID

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:

type: string
description: Country

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:
    # in staging, we want to show the banner to everyone
    - key: everyone
      segments: '*'
      percentage: 100
  production:
    # in production, we want to test the feature in Germany first, and
    # it will be enabled for 100% of the traffic
    - key: de
      segments: germany
      percentage: 100
    - key: everyone
      segments: '*' # everyone
      percentage: 0 # disabled for everyone else

Learn more in Features.

Linting#

We can lint the content of all our files 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 tags against each environment as defined in your featurevisor.config.js file.

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

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

Learn more in Building datafiles.

Deploy datafiles#

This is the part where you deploy the datafiles to your CDN or any other static file hosting service.

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

Learn more in Deployment.

Consume datafiles using the SDK#

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

Install SDK#

In your application, install the SDK first:

$ npm install --save @featurevisor/sdk

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

Initialize SDK#

You can initialize the SDK as follows:

import { createInstance } from '@featurevisor/sdk'
const datafileUrl =
  'https://cdn.yoursite.com/production/featurevisor-tag-all.json'
const datafileContent = await fetch(datafileUrl)
  .then((res) => res.json())
const f = createInstance({
  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.