JavaScript SDK

Install

npm install featurefuse-sdk
# or yarn add featurefuse-sdk

API

fetchSpecificFlags(environmentID, flagNames, url?)

Fetch only specific flags by name using the flag query parameter.

import { fetchSpecificFlags } from "featurefuse-sdk";

// Fetch a single flag
const chatFlag = await fetchSpecificFlags("ENV_ID", "chat_widget");

// Fetch multiple flags
const selectedFlags = await fetchSpecificFlags("ENV_ID", [
  "chat_widget",
  "beta_feature"
]);

init(options)

Fetches flags once by appending ?envID=... to the URL, so no custom headers are sent.

• options.environmentID (string) required
• options.url (string) override default endpoint
• options.flagNames (string[]|string) fetch only specific flag(s) (uses the flag query parameter)

import { init, hasFeature, getFlags } from "featurefuse-sdk";

// Default SaaS endpoint:
const flags = await init({ environmentID: "ENV_ID" });

// Fetch only specific flags:
const selectedFlags = await init({
  environmentID: "ENV_ID",
  flagNames: ["chat_widget", "beta_feature"]
});

hasFeature(name)

Check if a specific feature is enabled.

getFlags()

Retrieve last-fetched flags object.

fetchFlagsPost(environmentID, url?)

Fetch flags using POST method to completely bypass browser cache. This is useful when GET requests are being cached aggressively.

import { fetchFlagsPost } from "featurefuse-sdk";

// Fetch using POST to bypass cache
const flags = await fetchFlagsPost("ENV_ID");

React Integration

Supported React versions: 16.8+ (hooks), 17, 18, and 19

The React bindings use useSyncExternalStore for stable subscriptions across all React versions, with automatic fallback to use-sync-external-store/shim for React 16.8 and 17.

import {
  FeatureFuseProvider,
  useFlags,
  useFlag,
  useForceRefresh
} from "featurefuse-sdk/react";

function App() {
  return (
    <FeatureFuseProvider
      options={{
        environmentID: "ENV_ID",
        // pollInterval: 10000, // Optional: polling disabled by default
        // onError: (error) => console.error('Flag fetch failed:', error)
      }}
    >
      <HomePage />
    </FeatureFuseProvider>
  );
}

function HomePage() {
  // Get multiple flags
  const flags = useFlags(["chat_widget", "beta_feature"]);
  
  // Or get a single flag
  const chatFlag = useFlag("chat_widget");
  
  const forceRefresh = useForceRefresh();

  return (
    <>
      {chatFlag.enabled && <ChatWidget />}
      {flags.beta_feature?.enabled && <BetaFeature />}
      <button onClick={forceRefresh}>Refresh Flags</button>
    </>
  );
}

Provider Options

• environmentID (string) required - Your FeatureFuse environment ID
• url (string) - Override the default API endpoint
• flagNames (string[]) - Filter to only fetch specific flags
• pollInterval (number) - How often to poll for flag updates in ms (default: 0 = disabled)
• onError (function) - Error handler for fetch failures (error) => void

Hooks

• useFlags(keys?) - Get feature flags. Pass an array of flag names or leave empty for all flags
• useFlag(name) - Get a single feature flag by name. Returns { enabled: boolean, value?: unknown }
• useForceRefresh() - Get a function to manually refresh flags and trigger re-renders

Note: The SDK automatically triggers component re-renders when feature flags change, ensuring your UI stays in sync with flag updates.

StrictMode & Stability

• ✅ React StrictMode safe - No render loops or "Maximum update depth exceeded" errors
• ✅ Exponential backoff - Network failures don't cause tight re-render loops
• ✅ GET/POST fallback - Automatically tries POST if GET fails (CORS handling)
• ✅ Stable subscriptions - Uses useSyncExternalStore with proper change detection
• ✅ Polling control - Default polling is off; enable via pollInterval option

React Version Compatibility

• React 16.8+: Full support with hooks and automatic fallback to use-sync-external-store/shim
• React 17: Native support with use-sync-external-store/shim
• React 18: Native support with built-in useSyncExternalStore
• React 19: Full compatibility without React internals access

The SDK uses only public React APIs and properly externals React packages to avoid version conflicts.

Caching Behavior

The SDK implements multiple cache-busting strategies to ensure you always get the latest feature flag values:

• URL Cache Busting: Adds timestamp and last fetch time parameters to prevent URL-based caching
• HTTP Headers: Sends aggressive cache-busting headers including Cache-Control, Pragma, Expires, If-None-Match, and If-Modified-Since
• Request Object: Uses Request constructor with cache: "no-cache" to bypass browser cache
• POST Method: Provides fetchFlagsPost() function that uses POST requests to completely bypass GET caching
• Internal Cache: Maintains an in-memory cache

If you're still experiencing caching issues, you can:

1. Use the fetchFlagsPost() function to bypass GET caching completely
2. Use the useForceRefresh() hook in React components (automatically tries POST first)
3. Reduce the pollInterval in the React provider for more frequent updates

Other SDKs

• Python: pip install featurefuse-sdk
• C#: Install-Package FeatureFuse.SDK

Publishing

npm publish --access public
# or
yarn publish --access public

License

MIT