flipgate
v0.1.6
Published
React feature flags powered by [Flagly](https://flagly-platform.vercel.app). Toggle features from a dashboard — no code changes, no redeployment.
Readme
flipgate
React feature flags powered by Flagly. Toggle features from a dashboard — no code changes, no redeployment.
- Flags update within 10 seconds of toggling (instantly on tab refocus)
- Two APIs: a hook for logic, a gate component for wrapping UI
- Built on
flipgate-core— works with any React framework
Not using React? Use flipgate-core directly — works with Node.js, Vue, Svelte, and anywhere JavaScript runs.
Setup
1. Install
npm install flipgate2. Get an API key
- Go to flagly-platform.vercel.app
- Sign up and create a project
- Copy your API key — it looks like
flg_abc123...
Quick Start
Wrap your app once in app/layout.tsx:
import { FlaglyProvider } from 'flipgate';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<FlaglyProvider apiKey="flg_your_api_key">
{children}
</FlaglyProvider>
</body>
</html>
);
}Use flags anywhere in your app:
'use client';
import { useFeatureFlag } from 'flipgate';
export default function Page() {
const { enabled, loading } = useFeatureFlag('my-flag');
if (loading) return null;
return <p>{enabled ? 'New experience' : 'Classic view'}</p>;
}Go to your dashboard, toggle the flag, and it reflects in your app automatically.
API
<FlaglyProvider>
Wrap your root layout once. All hooks and gate components read from this context.
<FlaglyProvider
apiKey="flg_your_api_key"
apiUrl="https://flagly-platform.vercel.app" // optional — only needed if self-hosting
refreshInterval={10000} // optional — default 10s
>
{children}
</FlaglyProvider>| Prop | Type | Default | Description |
|---|---|---|---|
| apiKey | string | required | Your project API key |
| apiUrl | string | https://flagly-platform.vercel.app | Base URL of the Flagly platform |
| refreshInterval | number | 10000 | Poll interval in ms. Flags also refresh instantly on tab focus. |
useFeatureFlag(key)
Hook for reading a single flag value.
'use client';
import { useFeatureFlag } from 'flipgate';
export default function MyComponent() {
const { enabled, loading } = useFeatureFlag('my-flag');
if (loading) return null;
return <p>Flag is {enabled ? 'ON' : 'OFF'}</p>;
}| Return value | Type | Description |
|---|---|---|
| enabled | boolean | true if the flag is on. false by default until flags load. |
| loading | boolean | true on the first fetch before flags are available. |
Common mistake:
useFeatureFlagreturns an object, not a boolean. Always destructure it.// ❌ wrong — isEnabled is always truthy (it's an object) const isEnabled = useFeatureFlag('my-flag'); // ✅ correct const { enabled } = useFeatureFlag('my-flag');
<FeatureFlagGate>
Conditionally render UI based on a flag. Renders nothing while loading.
import { FeatureFlagGate } from 'flipgate';
<FeatureFlagGate flagKey="new-dashboard" fallback={<OldDashboard />}>
<NewDashboard />
</FeatureFlagGate>| Prop | Type | Default | Description |
|---|---|---|---|
| flagKey | string | required | The flag key to check |
| children | ReactNode | required | Rendered when the flag is ON |
| fallback | ReactNode | null | Rendered when the flag is OFF |
Flag keys
Flag keys are set in the Flagly dashboard when you create a flag. Use lowercase letters, numbers, and hyphens:
my-flag ✅
new-dashboard ✅
betaSearch ✅
my_flag ⚠️ underscore gets stripped — becomes myflagMake sure the key you pass to useFeatureFlag or flagKey exactly matches the key shown in the dashboard.
Framework support
Works with any React 18+ framework:
| Framework | Supported | |---|---| | Next.js (App Router) | ✅ | | Next.js (Pages Router) | ✅ | | Remix | ✅ | | Vite + React | ✅ | | Gatsby | ✅ | | Create React App | ✅ |
Not using React? Use flipgate-core for Node.js, Vue, Svelte, or plain JavaScript.
TypeScript
Fully typed — no extra setup needed.
import type { FlaglyConfig, Flags } from 'flipgate';How it works
flipgate is a thin React wrapper around flipgate-core. FlaglyProvider creates a FlagClient on mount, subscribes to flag updates, and pipes them into React context. All hooks and gate components read from that context.