dif-sh/dif

What is it?

Key features

• 01Flags and experiments are Markdown files with frontmatter, reviewed in pull requests.
• 02`dif validate` checks weights, surface references, audiences and experiment collisions.
• 03`dif build` generates a typed TypeScript client and context.json.
• 04Deterministic bucketing runs the same logic in the Rust CLI and the TypeScript SDK.
• 05`dif qa` shows the variant a given user receives and why.
• 06Optional connection to dif.sh Cloud for event ingest and analysis.

Use cases

• Running A/B tests on a Next.js or SvelteKit site without a hosted flag dashboard.
• Keeping flag history and experiment conclusions in git alongside the code.
• Letting AI coding agents create and retire flags by editing files in the repo.

Quick start

1. 1

   Install the dif CLI with npm (requires Node 20 or later)

   npm install -g @dif.sh/cli
2. 2

   Scaffold the dif/ directory, config and agent files in your repo

   dif init
3. 3

   Draft a new experiment file, then open it, set status: active, and run dif build

   dif new home-hero-cta --surface home
4. 4

   Compile active experiments into the typed TypeScript client

   dif build

Things to know

• !Requires Node 20 or later for the npm install path; a standalone binary is also offered.
• !The generated client is gitignored, so CI and deploy must run dif build before the app build.
• !The npm SDK packages are ESM-only and have no require() entry point.
• !Cloud analytics are optional and require a dif.sh Cloud publishable key.

Topics

FAQ

What is dif?

Feature flags and A/B tests stored as Markdown files in your repo, compiled by a CLI into a typed TypeScript client. dif keeps every feature flag and experiment as a single Markdown file with YAML frontmatter, checked into git next to the code it affects. The `dif` CLI validates these files (weights, surface references, audience attributes, and experiment collisions) and compiles active ones into a typed TypeScript client and a context.json file. The runtime SDK is dependency-free and uses deterministic bucketing, so a given user gets the same variant across page loads and devices without any assignment database or network call.

Is dif free to use? What license does it have?

dif is open source under the MIT license. Check the license terms before using it in commercial products.

Is dif still maintained?

Actively maintained. The last commit to dif was on Oct 16, 2026.

What can I use dif for?

Running A/B tests on a Next.js or SvelteKit site without a hosted flag dashboard. Keeping flag history and experiment conclusions in git alongside the code. Letting AI coding agents create and retire flags by editing files in the repo.

How do I install dif?

Install the dif CLI with npm (requires Node 20 or later): npm install -g @dif.sh/cli Scaffold the dif/ directory, config and agent files in your repo: dif init Draft a new experiment file, then open it, set status: active, and run dif build: dif new home-hero-cta --surface home Compile active experiments into the typed TypeScript client: dif build

Where can I get dif?

The source code and installation instructions are on GitHub: https://github.com/dif-sh/dif