@flagpole/react-native

A React Native SDK for integrating feature flags into your mobile application.

Features

• Real-time feature flag updates via WebSocket
• Environment-based flag configuration
• Simple API key authentication
• TypeScript support
• App state management (background/foreground handling)
• Network-aware connections
• Zero configuration required

Installation

npm install @flagpole/react-native

For React Native 0.60+, the native dependencies should auto-link. For older versions, you may need to manually link dependencies.

Usage

Basic Implementation

import React from "react";
import { View, Text } from "react-native";
import { FeatureFlagProvider, useFeatureFlag } from "@flagpole/react-native";

// Wrap your app with the provider
function App() {
  return (
    <FeatureFlagProvider
      apiKey="your_api_key_here"
      environments={["development"]}
    >
      <YourApp />
    </FeatureFlagProvider>
  );
}

// Use flags in your components
function MyComponent() {
  const isNewFeatureEnabled = useFeatureFlag("new-feature");

  return (
    <View>{isNewFeatureEnabled && <Text>This is a new feature!</Text>}</View>
  );
}

Available Hooks

// Check a specific flag
const isEnabled = useFeatureFlag("feature-name");

// Access all flags and metadata
const { flags, isLoading, error, isFeatureEnabled } = useFeatureFlags();

HOC Usage

import { withFeatureFlag } from "@flagpole/react-native";
import { View, Text } from "react-native";

const MyComponent = ({ title }) => (
  <View>
    <Text>{title}</Text>
  </View>
);

// Wrap component with feature flag
const FeatureFlaggedComponent = withFeatureFlag(MyComponent, "feature-name");

// Optional fallback component
const FeatureFlaggedWithFallback = withFeatureFlag(
  MyComponent,
  "feature-name",
  FallbackComponent
);

Configuration

Provider Props

| Prop | Type | Required | Default | Description | | ------------ | --------------- | -------- | -------- | ---------------------------------------- | | apiKey | string | Yes | - | Your API key from the FlagPole dashboard | | environments | Environment[] | No | All envs | Environments for feature flags | | children | React.ReactNode | Yes | - | Your app components |

Environment Configuration

The SDK automatically detects the environment based on the __DEV__ flag:

• Development: Uses localhost endpoints
• Production: Uses production endpoints

You can override this by setting specific environments in the provider.

React Native Specific Features

App State Management

The SDK automatically handles app state changes:

• Background: Disconnects WebSocket to save battery
• Foreground: Reconnects WebSocket and syncs flags

Network Handling

• Uses React Native's built-in fetch API
• Includes timeout handling and retry logic
• Graceful error handling for network failures

Error Handling

The SDK includes built-in error handling and will return false for any feature flags when:

• The connection fails
• The API key is invalid
• The flag doesn't exist

You can access error states through the useFeatureFlags hook:

import { useFeatureFlags } from "@flagpole/react-native";
import { View, Text, ActivityIndicator } from "react-native";

function MyComponent() {
  const { error, isLoading } = useFeatureFlags();

  if (isLoading) return <ActivityIndicator />;
  if (error) return <Text>Error: {error.message}</Text>;

  return <YourContent />;
}

Development

Prerequisites

• Node.js >= 16
• React Native development environment set up
• npm >= 7

Local Development

1. Clone the repository

git clone [repository-url]
cd react-native-sdk

2. Install dependencies

npm install

3. Build the SDK

npm run build

Testing with Local Projects

1. Build and link locally

npm run build
npm pack

2. In your React Native test project

npm install /path/to/flagpole-react-native-0.0.2.tgz

Platform Support

• ✅ iOS
• ✅ Android
• ✅ React Native >= 0.60
• ✅ Expo (managed workflow)
• ✅ TypeScript

Migration from Web SDK

The React Native SDK maintains API compatibility with the web SDK. Main differences:

1. Uses React Native's fetch instead of axios
2. Includes app state management
3. Uses React Native specific TypeScript types
4. Optimized for mobile network conditions

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

ISC

Support

For support, contact [support email/link]