featurevisor: feature flags as JSON files committed to Git

Git is the database, and the datafile is the artefact

The one paragraph summary in the README is worth reading closely, because it inverts the usual feature flag model.

You manage your Featurevisor project in a Git repository, you build and upload datafiles, which are static JSON files, to your CDN or custom server, and your application fetches the datafile and evaluates features using the SDKs.

So the runtime artefact is a static file, not an API call to a decision service. That has direct consequences. Evaluation happens in your process, which means no network hop on the hot path and no vendor latency in a flag check. It also means the flag configuration is reviewable in a pull request, and that changing a flag is a commit, a review and a CI run rather than a click in an admin panel.

The cost is that you own the delivery pipeline. The README is explicit about what you need to bring: a Git repository for managing the project declaratively, a CI/CD pipeline such as GitHub Actions for building and uploading the datafiles, and a CDN or custom server for serving the generated datafiles. The SDKs take care of the rest.

That is a meaningful operational commitment for a team that has never run a flag system before, and it is also the thing that makes the tool attractive to a team that already has a deployment pipeline and does not want a second control plane.

The project description calls this feature management with version control, and the repository topics include gitops, which names the pattern directly.

Four building blocks and four kinds of value

The vocabulary is small and deliberate, which is a good sign for a tool that has to be understood across several teams.

The building blocks are attributes, which are the unit of conditions, segments, which are reusable conditions for targeting users, features, which carry flag, variation and variable definitions, and global variables, which are independently evaluated configuration values.

Against those, the SDKs evaluate four kinds of value against a context your application provides. Flags are on and off values evaluated against rules. Variations are string values, which is what A/B tests are built from. Feature variables are typed values owned by a feature. And global variables are typed values with their own targeting and their own lifecycle.

The distinction between a feature variable and a global variable is the one worth holding on to. A feature variable belongs to a feature and dies with it. A global variable is evaluated on its own, which is what you want for something like a pricing configuration or a support message that is not tied to a rollout.

The JavaScript SDK also evaluates composed variables, which group flags, variations and variables into a single object with optional overrides applied after assembly. The documentation warns that a supporting SDK must be deployed before serving a composed datafile, which is a sensible constraint, since a client that cannot understand the composed form would silently get the wrong shape.

The use case list in the README shows how wide this is meant to be: decoupling deployments from releases, progressive delivery, testing in production, A/B and multivariate experiments, mutually exclusive experiments, role based gating, entitlements, remote configuration, ownership and governance, trunk based development, microfrontends, feature dependencies and safe deprecation.

Fifteen SDKs and a conformance suite to keep them honest

The supported SDK list is unusually long for a project of this size: JavaScript, React, React Native, Vue.js, Next.js, Go, Python, PHP, Ruby, Java, Kotlin, Swift, Rust and Elixir, plus OpenFeature providers for Node.js, browsers, Go, Swift, Java and Kotlin, Ruby, Python, PHP, Rust and Elixir.

Supporting this many languages is only half the problem. The other half is making sure they agree with each other, and the repository layout shows serious attention to that. There is a `conformance/` directory at the top level, and the Makefile has targets named `test-runner-conformance`, `test-mutation-conformance` and `check-conformance-fixtures`, with the runner conformance script taking a language argument and invoked as `node scripts/test-runner-conformance.mjs javascript`.

There is a separate `test-mutation-conformance.mjs` target as well, which suggests that the same fixtures are run against a mutated implementation to confirm the tests actually fail when behaviour changes. That is the difference between a test suite and a conformance suite.

The Makefile comments are also candid about what is left out of continuous integration. The slower checks, described as compiled package consumers, browsers, the CLI end to end, JavaScript conformance, editor schemas, release configuration and bundle size budgets, are kept out so that CI stays fast, and `make check` runs them after a build. The browser checks need a local Chromium compatible browser.

The npm scripts list is equally specific: `test:react-minimum` checks a minimal React consumer, `test:package-exports` and `test:packed-packages` check the published shape of the packages, `test:browser` and `test:catalog-browser` run the browser tests, `bundle-sizes` measures them, and `benchmark:sdk-dependencies` measures the dependency impact of the SDKs with `--expose-gc`.

That last one matters for a flag SDK, because the whole point of a client side evaluator is that it stays small.

Installing the AI agent skill is a single npx command

The most unusual thing about featurevisor right now is that it ships an official skill for AI coding agents.

The documentation describes it as teaching agents such as Claude Code, Cursor, Codex and OpenCode how to work with your project: creating features and segments, writing rollout rules and test specs, debugging evaluations, promoting between sets, and integrating SDKs into your applications.

Installing it into your Featurevisor project, or into your app repository, goes through skills.sh:

npx skills add featurevisor/featurevisor

The examples given for prompting an agent are the ones that show the intended workflow. You can ask it to create a `showWishlist` feature tagged web starting at 5 percent. You can ask it why `checkout` is disabled for a particular userId in a particular country, which is a debugging question rather than a generation one. And you can ask it to roll out `newEditor` to employees first, then beta users, then everyone, which is the progressive delivery pattern expressed as a request.

The skill's source lives in the repository under `skills/`, and the root package.json has a `test:skills` script running `node --test skills/tests/*.test.mjs`, so the skill's behaviour is tested like any other part of the project.

There is also a visual review tool. The documentation says to pair the agent with `npx featurevisor catalog` running locally, which opens a browser view of every change the agent made. That is the piece that makes agent-driven flag editing tolerable, because the risk with an agent writing your flag definitions is that it writes something plausible and wrong, and a visual diff catches that in a way that reading YAML does not.

A Lerna monorepo with more than a dozen packages

The repository is a Lerna monorepo. The root package.json is private, at version 0.0.0, with workspaces covering `packages/*` and `examples/*`, and the build and test commands delegate to `lerna run`.

The examples directory is worth looking at, because it is the documentation of what the project file format can express. There are directories for a basic example, composition, environments, JSON, a namespace with a slash, no environments at all, sets, targets, test environments, TOML, YAML, and an example with environments. That list is a catalogue of configuration shapes, and having a runnable example for each of them removes most of the guesswork from authoring a first project.

The build tooling is modern and deliberately multi-format. The root devDependencies include esbuild, terser, vite and swc, and there are three separate tsconfig files, `tsconfig.cjs.json`, `tsconfig.esm.json` and `tsconfig.eslint.json`, which is the standard way to emit both CommonJS and ES module builds from one source tree. TypeScript is at ^6.0.3, ESLint at ^10.5.0, Jest at ^30.4.2 and Lerna at ^10.1.1.

The `Makefile` wraps the npm scripts into named targets, and the `audit:production` target runs `npm audit --omit=dev`, so the production dependency tree is checked separately from the development one. There is also a `.claude-plugin/` directory at the root, an `AGENTS.md`, and a `.nvmrc` pinning the Node version.

On the repository side of things, the project is MIT licensed, with the copyright held by Fahad Heylaal, who also built it.

What committing flags to Git does not solve

The GitOps model is genuinely good at some things and it has costs that a vendor dashboard does not have.

What it solves well is review and governance. A flag that changes pricing or entitlement becomes a diff in a pull request, with a reviewer who can see what else changed. It also solves reproducibility, because the flag state at any past commit is knowable, and it removes the dependency on a vendor being reachable during an incident.

What it does not solve is the operational access problem. If a non engineer needs to turn something off at 3am, Git is a poor tool for it: it needs a branch, a commit, a CI run, and a CDN deploy, and that is a several minute path in the best case. Vendor dashboards give you a button for exactly this. The use case list mentions establishing feature ownership and governance, and mutual exclusivity of experiments, which are the problems a repository and a pull request genuinely help with, and they do not mention emergency kill switches, which is where the model is weakest.

There is a second limit around experimentation. The SDKs evaluate variations and return assignments, which is what you need to randomise consistently across a user's sessions. Running the experiment, collecting the metrics and deciding on significance is a separate system, and the README does not claim otherwise. If your experimentation stack is a statistical platform, featurevisor has to fit into it rather than replace it.

The third limit is operational maturity. The SDK is evaluated in your process, which is a performance win, but it also means your application now carries a dependency on the datafile format and on the SDK version. The bundle size budgets and the package export tests in the Makefile exist because that is a real ongoing cost.

The alternative approach to name is a hosted feature flag service with its own dashboard, targeting rules engine and streaming delivery. The difference in approach is ownership: a hosted service makes the flag state a mutable runtime resource that you query, while featurevisor makes it a build artefact you version. Everything else follows from that, including the review story and the emergency toggle story.

Editorial conclusion

Adopt featurevisor if your team already works in Git and wants feature flag definitions reviewed in pull requests rather than edited in a vendor dashboard, and if you can accept building and serving datafiles yourself. Do not adopt it if you need a hosted UI for non engineers to toggle flags, since the operational surface is a CLI and a Git repository. Verify first that your stack has an SDK in the supported list, that you can operate a CDN or static server for the datafiles, and that your existing experimentation metrics pipeline can consume the variation assignments the SDKs return.

Frequently asked questions

Official sources

1. featurevisor/featurevisor on GitHub
2. Issues
3. License: MIT
4. Project website
5. README