Featurevisor
See all posts

Featurevisor v3.0 is here!

By Fahad Heylaal on

Featurevisor v3.0 is here, focused on making projects easier to organize and scale, datafiles easier to shape, and SDKs easier to use consistently across multiple different languages, with first class support for AI agents.

This is a breaking release, but the generated datafile schema remains version 2.

Upgrade your Featurevisor project first and publish v3-generated datafiles, then upgrade application SDKs one at a time with each application team.

What's new?

The biggest changes in v3 are:

Catalog in AI Agents

Use skills to start the Catalog server and browse definitions in your AI agent's browser. Ask the agent to make changes as you review.

Catalog

When I started Featurevisor, I built it with the idea of developers writing the definitions by hand declaratively. Now I feel we live in a different world where AI agents are more capable of generating the definitions for us better.

Declarative definitions give agents a format to read and edit. Catalog lets you inspect those definitions alongside your prompts.

Targets for datafiles

Scopes were previously introduced to make smaller datafiles from partially known contexts. In v3, that responsibility belongs to Targets.

Targets

Targets live as files in the targets directory:

targets/web.yml
description: Web datafile
# pick all features tagged with 'web'
tag: web
# apply partially known context upfront
# to reduce conditions/segments/rules in generated datafile
context:
  platform: web

Select features directly:

targets/checkout.yml
description: Checkout features
includeFeatures:
  - checkout*
  - shared.navigation
excludeFeatures:
  - checkout.internal*

Every datafile is now produced from a target. The smallest possible target is simply:

targets/all.yml
description: All features

Unless anything else is specified, the target will include all features in the project.

The generated datafiles follow the convention of datafiles/<environment>/featurevisor-<target>.json.

Sets and promotions

With Sets, which is optional to adopt, a project can be split into independent trees:

sets/
├── dev/
├── staging/
└── production/

Each set owns its own attributes, segments, features, targets, and tests. Use Promotions to move definitions forward:

Command
npx featurevisor promote --from=dev --to=staging --apply

This works well for teams that want release lanes, ownership boundaries, or distinct surfaces while keeping everything managed through Git.

The same approach based on sets can also be used for completely different areas of your business, such as different products, teams, or geographies, that need to be managed independently.

SDKs

The JavaScript SDK has a smaller and clearer public API:

import {
  createFeaturevisor,
  type Featurevisor,
  type FeaturevisorOptions,
  type FeaturevisorModule,
} from '@featurevisor/sdk'

Modules replace hooks:

const trackingModule: FeaturevisorModule = {
  name: 'tracking',
  after(evaluation) {
    // send exposure or diagnostic data to your own system
    return evaluation
  },
}
const f = createFeaturevisor({
  datafile,
  modules: [trackingModule],
})

Diagnostics are now the standard way to observe SDK behaviour:

const f = createFeaturevisor({
  logLevel: 'info',
  onDiagnostic(diagnostic) {
    // send to your observability system
  },
})

Nothing changes for the evaluation methods.

The Go, Swift, Java, Ruby, Python, and PHP SDKs have also been aligned with the same v3 behaviour where practical for each language.

Datafile schema

Featurevisor v3 still generates schema version 2 datafiles:

{
  "schemaVersion": "2"
}

The old v1 datafile generation path and --schema-version selection are gone from active usage.

If you still have a consumer that requires v1 datafiles, keep using an older Featurevisor v2 CLI for that consumer while you migrate it.

Migration guide

The full migration guide is available here:

The recommended path is:

  1. Upgrade your Featurevisor project and generate v3 datafiles.
  2. Publish the datafiles.
  3. Upgrade application SDKs one at a time.

Because the datafile schema remains version 2, this can be done incrementally for applications already using v2-compatible SDKs.

Where we stand today

Featurevisor has come a long way since its inception in 2023, going stable with v1 in the same year later.

Since v2, more SDKs have joined the project, alongside skills for AI agents and Catalog for browsing definitions.

V3 focuses on organizing larger projects with thousands of features, segments and rules. Targets and Sets give teams more control over what each application loads and which definitions they manage together.

Based on the numbers from npm, the usage of Featurevisor has been growing steadily. And word of mouth will play a key role in the future. I am hoping the v3 release will help it grow even faster.

Going forward

I have been quietly expanding the visor family with Messagevisor (for i18n and l10n needs) and Eventvisor (for analytics schema governance), and I will be spending some time there to make them stable and production ready.

There will be synergy between the tools, like how Messagevisor already has a Featurevisor module. More to come on that front.

Goal is still to keep them as separate projects, while making it easier to use them together. Once you get used to using one, it will feel natural to use the others too.

And as more visors are adopted together, the faster you can leverage agentic workflows for the areas they cover. More recipes will arrive soon showing how to maximize the benefits of that.

Support

Star on GitHub, and follow me on Twitter / LinkedIn to get updates on the future of Featurevisor and the visor family.