Gatera

The dead simple, zero-config feature flag SDK with full TypeScript support

Installation

npm install gatera

Quick Start

import { flags } from 'gatera'

// Check if a feature is enabled
if (flags.isEnabled('new-checkout')) {
  // Your new feature code
  showNewCheckoutFlow()
} else {
  // Fallback code
  showOldCheckoutFlow()
}

// Get all flags
const allFlags = flags.getAll()
console.log(allFlags) // { 'new-checkout': true, 'dark-mode': false }

Zero Configuration

The SDK automatically:

🎯 Detects your environment (development/staging/production)
🔍 Finds your Gatera instance via URL detection
📦 Caches flags locally for optimal performance
🔄 Auto-refreshes flags in the background
🛡️ Handles errors gracefully with fallbacks

Advanced Usage

Custom Configuration

import { configure } from 'gatera'

configure({
  baseUrl: 'https://flags.yourcompany.com',
  environment: 'production',
  userId: 'user-123',
  refreshInterval: 60000, // 1 minute
  fallbacks: {
    'new-feature': false,
    'maintenance-mode': true
  }
})

Context-Aware Flags

import { flags } from 'gatera'

// Pass context for personalized flags
const isEnabled = flags.isEnabled('premium-features', {
  userId: 'user-456',
  environment: 'production'
})

Manual Control

import { flags } from 'gatera'

// Manually refresh flags
await flags.refresh()

// Create isolated client
import { createFeatureFlagClient } from 'gatera'

const client = createFeatureFlagClient({
  environment: 'staging'
})

if (client.isEnabled('beta-feature')) {
  // Beta feature code
}

Environment Detection

The SDK automatically detects your environment:

Development: localhost, *.dev, NODE_ENV=development
Staging: *.staging.*, *.stage.*, NODE_ENV=staging
Production: Everything else, NODE_ENV=production

Rollout Percentages

Flags with rollout percentages are consistently applied per user:

// 30% rollout - same user always gets same result
flags.isEnabled('gradual-rollout') // Stable per user

TypeScript Support

Full type safety out of the box:

// Auto-complete for all your flag keys
if (flags.isEnabled('new-checkout')) { // ✅ Auto-complete
  // TypeScript knows this is a boolean
}

// Type-safe value retrieval
const theme = flags.getValue('theme', 'light') // ✅ Returns string
const isEnabled = flags.getValue('feature', false) // ✅ Returns boolean

Performance

🚀 <3KB gzipped - Tiny bundle size
⚡ Local caching - Flags cached in memory and localStorage
🔄 Smart refreshing - Only fetches when needed
🛡️ Graceful degradation - Works offline with cached flags

Error Handling

The SDK never breaks your application:

// Unknown flags return fallback values
flags.isEnabled('unknown-flag') // Returns false

// Network errors use cached flags
flags.isEnabled('cached-flag') // Returns last known value

// Configure fallbacks for critical flags
configure({
  fallbacks: {
    'payment-system': true, // Always enabled if fetch fails
    'maintenance-mode': false // Always disabled if fetch fails  
  }
})

Framework Integration

React

import { flags } from 'gatera'
import { useState, useEffect } from 'react'

function MyComponent() {
  const [isEnabled, setIsEnabled] = useState(false)
  
  useEffect(() => {
    setIsEnabled(flags.isEnabled('new-ui'))
  }, [])
  
  return isEnabled ? <NewUI /> : <OldUI />
}

Vue

<template>
  <NewCheckout v-if="isNewCheckoutEnabled" />
  <OldCheckout v-else />
</template>

<script setup>
import { flags } from 'gatera'
import { ref, onMounted } from 'vue'

const isNewCheckoutEnabled = ref(false)

onMounted(() => {
  isNewCheckoutEnabled.value = flags.isEnabled('new-checkout')
})
</script>

Next.js

// pages/index.tsx
import { flags } from 'gatera'

export async function getServerSideProps() {
  // SDK works in Node.js too
  const showBeta = flags.isEnabled('beta-features')
  
  return {
    props: { showBeta }
  }
}

API Reference

`flags.isEnabled(key, context?)`

Check if a feature flag is enabled.

`flags.getValue(key, defaultValue, context?)`

Get a flag value with type-safe default.

`flags.getAll()`

Get all flags as key-value object.

`flags.refresh()`

Manually refresh flags from server.

`configure(config)`

Configure the global SDK instance.

`createFeatureFlagClient(config)`

Create an isolated SDK instance.

License

MIT