Getting started

npm install @evanion/react-feature @evanion/feature

yarn add @evanion/react-feature @evanion/feature

pnpm add @evanion/react-feature @evanion/feature

import { createFeatures } from '@evanion/feature';
import { FeatureProvider, useFeatureEnabled } from '@evanion/react-feature';
import { renderToStaticMarkup } from 'react-dom/server';
 
const features = createFeatures([{ key: 'express-pickup', enabled: true }]);
const context = {
  targetingKey: 'cust-0042',
  now: new Date('2026-11-01T00:00:00Z'),
};
 
function Checkout() {
  if (!useFeatureEnabled('express-pickup')) return <p>Standard checkout</p>;
  return <p>Checkout with express pickup</p>;
}
 
const html = renderToStaticMarkup(
  <FeatureProvider features={features} context={context}>
    <Checkout />
  </FeatureProvider>,
);
 
html; // -> '<p>Checkout with express pickup</p>'

// The instant the server rendered at, so both sides read the same clock.
const now = new Date('2026-11-01T00:00:00Z');
 
function Flags({
  customerId,
  children,
}: {
  customerId: string;
  children: ReactNode;
}) {
  const context = useMemo(
    () => ({ targetingKey: customerId, now }),
    [customerId],
  );
 
  return (
    <FeatureProvider features={features} context={context}>
      {children}
    </FeatureProvider>
  );
}
 
const html = renderToStaticMarkup(
  <Flags customerId="cust-0042">
    <Checkout />
  </Flags>,
);
 
html; // -> '<p>Express</p>'

import { createFeatures } from '@evanion/feature';
import { FeatureProvider, useFeature } from '@evanion/react-feature';
import type { ReactElement } from 'react';
import { renderToStaticMarkup } from 'react-dom/server';
 
const features = createFeatures([{ key: 'express-pickup', enabled: true }]);
 
function Misspelled() {
  return <p>{useFeature('express-delivery').reason}</p>;
}
 
const attempt = (element: ReactElement) => {
  try {
    return renderToStaticMarkup(element);
  } catch (error) {
    return String(error);
  }
};
 
const page = (
  <FeatureProvider features={features}>
    <Misspelled />
  </FeatureProvider>
);
 
attempt(page); // -> 'Error: feature "express-delivery" is not configured in this <FeatureProvider>'
// @ts-expect-error -- the store's keys are checked at compile time
features.isEnabled('express-delivery'); // -> false

import { createFeatures } from '@evanion/feature';
import { createFeatureContext } from '@evanion/react-feature';
import { renderToStaticMarkup } from 'react-dom/server';
 
const features = createFeatures([
  {
    key: 'checkout-cta',
    enabled: true,
    variants: [
      { name: 'control', weight: 50 },
      { name: 'blue', weight: 50, value: { label: 'Get it' } },
    ],
  },
]);
 
const { FeatureProvider, useVariant } = createFeatureContext(features);
 
function Cta() {
  const { value } = useVariant('checkout-cta');
  return <button type="button">{value?.label ?? 'Buy'}</button>;
}
 
function Misspelled() {
  // @ts-expect-error -- 'checkout-button' is not a key of this store
  return <p>{useVariant('checkout-button').variant}</p>;
}
 
const forCustomer = (targetingKey: string) =>
  renderToStaticMarkup(
    <FeatureProvider context={{ targetingKey }}>
      <Cta />
    </FeatureProvider>,
  );
 
forCustomer('cust-0199'); // -> '<button type="button">Get it</button>'
forCustomer('cust-0042'); // -> '<button type="button">Buy</button>'

const features = createFeatures([
  {
    key: 'express-pickup',
    enabled: true,
    rules: [{ id: 'a-share', rollout: { percent: 25 } }],
  },
]);
type ShopDecisions = DecisionSet<{ 'express-pickup': never }>;
 
// app/flags.tsx, a client module ('use client')
function Flags({
  decisions,
  children,
}: {
  decisions: ShopDecisions;
  children: ReactNode;
}) {
  return (
    <FeatureProvider features={features} decisions={decisions}>
      {children}
    </FeatureProvider>
  );
}
 
// app/layout.tsx, a Server Component
function Layout({
  customerId,
  children,
}: {
  customerId: string;
  children: ReactNode;
}) {
  const decisions = features.snapshot({ targetingKey: customerId });
  // Props crossing into a client module are serialised; JSON is the same test.
  const sent: ShopDecisions = JSON.parse(JSON.stringify(decisions));
 
  return <Flags decisions={sent}>{children}</Flags>;
}
 
const forCustomer = (customerId: string) =>
  renderToStaticMarkup(
    <Layout customerId={customerId}>
      <Checkout />
    </Layout>,
  );
 
forCustomer('cust-0042'); // -> '<p>Express</p>'
forCustomer('cust-0107'); // -> '<p>Standard</p>'

const features = createFeatures([
  { key: 'express-pickup', enabled: true },
  { key: 'gift-cards', enabled: true },
]);
 
function Checkout() {
  return <p>{useFeatureEnabled('express-pickup') ? 'Express' : 'Standard'}</p>;
}
 
function Audit() {
  const { reason } = useFeature('express-pickup');
  const { variant } = useVariant('express-pickup');
  const published = Object.keys(useFeatures()).sort();
  return (
    <p>{`${reason}/${variant ?? 'no variant'}: ${published.join(', ')}`}</p>
  );
}
 
const fromServer = features.snapshot();
fromServer.decisions['express-pickup'] = {
  key: 'express-pickup',
  enabled: false,
  reason: 'explicitly-off',
};
// A set shipped as JSON reaches the provider unchecked.
const snapshot = JSON.parse(
  JSON.stringify({
    ...fromServer,
    decisions: { 'gift-cards': fromServer.decisions['gift-cards'] },
  }),
);
 
const served = (
  <FeatureProvider features={features} decisions={fromServer}>
    <Checkout />
  </FeatureProvider>
);
const partial = (
  <FeatureProvider features={features} decisions={snapshot}>
    <Checkout />
  </FeatureProvider>
);
const audited = (
  <FeatureProvider features={features} decisions={fromServer}>
    <Audit />
  </FeatureProvider>
);
 
attempt(served); // -> '<p>Standard</p>'
attempt(partial); // -> 'Error: feature "express-pickup" is not configured in this <FeatureProvider>'
attempt(audited); // -> '<p>explicitly-off/no variant: express-pickup, gift-cards</p>'