Getting Started
flagfish-client-react is a lightweight React SDK for seamless feature flag integration. Built with React context and hooks, it provides optimal performance and developer experience.
Installation
Install the SDK using npm:
1npm install flagfish-client-reactBasic Usage
Wrap Your App
Wrap your application with the FlagFish provider to enable feature flags throughout your app.
1"use client"; // For Next.js App Router
2import { FlagFishProvider } from "flagfish-client-react";
3
4export const FlagFishWrapper = ({ children }: { children: React.ReactNode }) => {
5 return (
6 <FlagFishProvider
7 apiKey={process.env.NEXT_PUBLIC_FLAGFISH_API_KEY!}
8 options={{
9 refreshInterval: 60000, // Refresh every 60 seconds
10 fallbackValues: {} // Optional default values
11 }}
12 >
13 {children}
14 </FlagFishProvider>
15 );
16};Use the Feature Flag
Access feature flags in your components using the useFlagByKey hook. Handle loading and error states appropriately.
1import { useFlagByKey } from "flagfish-client-react";
2
3const FeatureComponent = () => {
4 const { isEnabled, loading, error } = useFlagByKey({
5 name: "new-ai-feature",
6 autoRun: true
7 });
8
9 if (loading) return <p>Loading...</p>;
10 if (error) return <p>Error loading feature flag</p>;
11
12 return (
13 <div>
14 {isEnabled ? (
15 <div className="new-feature">
16 <h2>🚀 New AI-Powered Feature</h2>
17 <p>Experience our cutting-edge AI capabilities!</p>
18 </div>
19 ) : (
20 <div className="classic-feature">
21 <h2>Classic Feature</h2>
22 <p>Reliable and time-tested functionality</p>
23 </div>
24 )}
25 </div>
26 );
27};
28
29export default FeatureComponent;Advanced Usage
Pro Features
Use targeting options for A/B testing and user segmentation. Combine multiple flags for complex feature rollouts.
1import { useFlagByKey } from "flagfish-client-react";
2
3// Targeting specific users or segments
4const PremiumFeature = ({ userId, userTier }: Props) => {
5 const { isEnabled } = useFlagByKey({
6 name: "premium-dashboard",
7 autoRun: true,
8 options: {
9 property: "userTier",
10 value: userTier // e.g., "premium", "enterprise"
11 }
12 });
13
14 return isEnabled ? <PremiumDashboard /> : <StandardDashboard />;
15};
16
17// Using multiple flags
18const ExperimentalFeatures = () => {
19 const darkMode = useFlagByKey({ name: "dark-mode-ui", autoRun: true });
20 const betaFeatures = useFlagByKey({ name: "beta-features", autoRun: true });
21
22 return (
23 <div className={darkMode.isEnabled ? "dark" : "light"}>
24 {betaFeatures.isEnabled && <BetaFeaturePanel />}
25 </div>
26 );
27};Best Practices
Security
Never expose your API keys in client-side code. Use environment variables and keep keys secure.
Error Handling
Always handle errors gracefully. Provide fallback values to ensure your app works even if flags fail to load.
Performance
Use the refreshInterval option to control how often flags are updated. Balance freshness with performance.
Testing
Test both enabled and disabled states. Use fallback values in tests to ensure consistent behavior.
Quick Tips
- •Start with simple boolean flags before implementing complex targeting rules
- •Use descriptive flag names that clearly indicate the feature (e.g., "checkout-v2", "dark-mode")
- •Document your flags and their intended behavior for team collaboration
- •Clean up old flags after features are fully rolled out or removed