@xgaming/xg-flags

Drop-in SDK package for feature flags with LaunchDarkly relay proxy support. This package allows your customers to supply their own configuration (relayUrl, envId, custom headers) when they boot the client.

Installation

⚠️ React Native Only: This package is designed exclusively for React Native environments and will not work in Node.js, browsers, or other JavaScript runtimes.

npm install @xgaming/xg-flags
# Peer dependencies (install in your React Native app)
npm install @react-native-async-storage/async-storage react-native-sse

For React Native < 0.71, also install Buffer polyfill:

npm install buffer
# Add to your App.tsx: import { Buffer } from 'buffer'; global.Buffer = Buffer;

Quick Start

Basic Usage (without React context)

import { createXGFlagsClient, XGUser } from '@xgaming/xg-flags';

const flags = createXGFlagsClient({
  relayUrl: 'https://xgexp.xgaming.club',
  envId: '<CLIENTSIDE_ENV_ID>',     // provided by your customer
  headers: { /* optional auth header if your API GW requires */ }
});

const user: XGUser = { key: '42', plan: 'pro' };
await flags.register(user);

if (flags.get('newUI')) {
  // render new experience
}

With React Context Provider

// App.tsx
import React from 'react';
import { FlagProvider, createXGFlagsClient, useFlag } from '@xgaming/xg-flags';

const client = createXGFlagsClient({
  relayUrl: 'https://xgexp.xgaming.club',
  envId: 'abcd1234abcd1234abcd1234abcd1234'
});

export default function App() {
  return (
    <FlagProvider client={client} user={{ anonymous: true }}>
      <Home />
    </FlagProvider>
  );
}

// Home.tsx
const Home = () => {
  const promo = useFlag<string>('welcomeMessage', 'Hello!');
  return <Text>{promo}</Text>;
};

Configuration Options

| Option | Default | Description | | ------------- | ---------- | ---------------------------------------------------------- | | relayUrl | (none) | Base URL of Relay Proxy (must include protocol). | | envId | (none) | LaunchDarkly client‑side environment ID. | | cachePrefix | XGFlags: | Prefix for AsyncStorage keys. | | stream | true | Disable if you want poll‑only behaviour. | | headers | {} | Extra HTTP/SSE headers (e.g., auth token, CF worker hook). |

API Reference

XGFlagsClient

Methods

• register(user: XGUser): Promise<void> - Identify/switch user
• refresh(): Promise<void> - Manual refresh (pull latest once)
• get<T>(key: string): T | undefined - Get current flag value
• onChange(callback: (flags: FlagMap) => void): () => void - Subscribe to flag changes

React Hooks

• useFlag<T>(key: string, fallback: T): T - Get flag value with fallback

Testing

React Native Testing

For proper testing in React Native environments, use tools like:

• React Native Testing Library with Metro bundler
• Detox for end-to-end testing
• Jest with React Native preset

Node.js Testing (Advanced)

If you need to test in Node.js (e.g., for CI/CD), you'll need to mock the React Native dependencies:

// __mocks__/@react-native-async-storage/async-storage.js
const mockAsyncStorage = {
  getItem: jest.fn(() => Promise.resolve(null)),
  setItem: jest.fn(() => Promise.resolve()),
  removeItem: jest.fn(() => Promise.resolve()),
  clear: jest.fn(() => Promise.resolve()),
};

module.exports = mockAsyncStorage;

// __mocks__/react-native-sse.js
class MockEventSource {
  constructor(url, options) {
    this.url = url;
    this.options = options;
  }
  addEventListener() {}
  close() {}
}

module.exports = MockEventSource;

Environment Errors

If you see ReferenceError: window is not defined or similar errors, it means you're trying to use this package outside of React Native. Please ensure you're running in a proper React Native environment.

License

MIT