featurefuse-sdk

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:

• Use the fetchFlagsPost() function to bypass GET caching completely
• Use the useForceRefresh() hook in React components (automatically tries POST first)
• 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