StatsIG SDK A TypeScript/JavaScript SDK for feature flags and analytics, with first-class React support. Installation bashnpm install @your-org/statsig-sdk

or

yarn add @your-org/statsig-sdk Quick Start Vanilla JavaScript/TypeScript typescriptimport { initialize, checkFeatureFlag, trackCustomEvent } from '@your-org/statsig-sdk'

// Initialize the SDK initialize({ apiKey: 'your-api-key', userAttributes: { age: 28, country: 'US', subscription_tier: 'premium' } })

// Check feature flags const result = await checkFeatureFlag('new-feature') if (result.enabled) { console.log('Feature enabled for segments:', result.matchedSegments) // Show new feature }

// Track events trackCustomEvent('button_clicked', { button: 'sign-up', page: '/landing' }) React tsximport React from 'react' import { StatsigProvider, useFeatureFlag, FeatureFlag } from '@your-org/statsig-sdk'

// 1. Wrap your app with StatsigProvider function App() { return ( <StatsigProvider config={{ apiKey: 'your-api-key', userAttributes: { age: 28, country: 'US', subscription_tier: 'premium' } }} > ) }

// 2. Use feature flags in components function Dashboard() { const { enabled, loading } = useFeatureFlag('new-dashboard')

if (loading) return Loading...

return (

  {/* Or use the component */}
  <FeatureFlag flagKey="premium-features" fallback={<UpgradePrompt />}>
    <PremiumFeatures />
  </FeatureFlag>
</div>

) } Core Concepts User Attributes Instead of user IDs, this SDK uses user attributes to determine feature flag eligibility based on segments you create in your dashboard. typescriptconst userAttributes = { age: 25, // Number country: 'US', // String subscription_tier: 'premium', // String device_type: 'mobile', // String signup_date: '2024-01-15' // String (dates) } Segments Create segments in your dashboard with criteria like:

age > 25 (users older than 25) country = "US" (US users) subscription_tier in "premium,enterprise" (premium users)

Feature Flags Feature flags are associated with segments. When you check a flag, the SDK evaluates your user attributes against segment criteria. API Reference Core Functions initialize(config: StatsigConfig) Initialize the SDK with your configuration. typescriptinterface StatsigConfig { apiKey: string // Your project API key baseUrl?: string // Custom API endpoint userAttributes?: Record<string, any> // Default user attributes sessionId?: string // Custom session ID } checkFeatureFlag(flagKey: string, userAttributes?: Record<string, any>) Check if a feature flag is enabled. typescriptconst result = await checkFeatureFlag('new-checkout', { subscription_tier: 'premium' })

// Returns: { enabled: boolean, matchedSegments?: string[], reason?: string } trackCustomEvent(eventName: string, properties?: Record<string, any>) Track a custom event. typescriptawait trackCustomEvent('purchase_completed', { amount: 99.99, currency: 'USD', item_count: 3 }) React Hooks useFeatureFlag(flagKey: string, userAttributes?: Record<string, any>) Hook for checking feature flags with loading states. tsxconst { enabled, loading, matchedSegments } = useFeatureFlag('new-feature') useTracking() Hook for tracking events. tsximport { useTracking } from '@your-org/statsig-sdk'

const { trackClick, trackPageView, trackCustomEvent } = useTracking()

const handleClick = () => { trackClick('hero-button', { variant: 'blue' }) } useUserAttributes() Hook for managing user attributes. tsximport { useUserAttributes } from '@your-org/statsig-sdk'

const { updateAttributes, getAttributes } = useUserAttributes()

// Update when user logs in useEffect(() => { updateAttributes({ age: user.age, subscription_tier: user.plan }) }, [user]) React Components Conditional rendering based on feature flags. tsx<FeatureFlag flagKey="premium-features" userAttributes={{ subscription_tier: 'premium' }} fallback={} loading={}

function UserProfile({ user }) { const { updateAttributes } = useUserAttributes()

useEffect(() => { updateAttributes({ age: user.age, country: user.country, subscription_tier: user.plan, days_since_signup: Math.floor((Date.now() - user.createdAt) / (1000 _ 60 _ 60 * 24)) }) }, [user])

return ... } A/B Testing tsxconst { variant } = useVariant('homepage-test', ['control', 'variant-a', 'variant-b'])

switch (variant) { case 'variant-a': return case 'variant-b': return default: return } Page View Tracking with React Router tsximport { useLocation } from 'react-router-dom' import { useTracking } from '@your-org/statsig-sdk'

function PageTracker() { const location = useLocation() const { trackPageView } = useTracking()

useEffect(() => { trackPageView(location.pathname) }, [location])

return null } Error Handling tsxconst { enabled, loading, error } = useFeatureFlag('risky-feature')

if (error) { // Flag evaluation failed, use safe default return } Environment Setup Environment Variables bash# .env REACT_APP_STATSIG_API_KEY=your_api_key_here REACT_APP_STATSIG_BASE_URL=https://your-app.vercel.app TypeScript Support The SDK is written in TypeScript and includes full type definitions. typescriptimport type { StatsigConfig, FeatureFlagResult } from '@your-org/statsig-sdk' Examples E-commerce tsxfunction CheckoutButton({ cart }) { const { enabled: expressCheckout } = useFeatureFlag('express-checkout') const { trackCustomEvent } = useTracking()

const handleCheckout = () => { trackCustomEvent('checkout_started', { cart_value: cart.total, checkout_type: expressCheckout ? 'express' : 'standard' }) }

return expressCheckout ? ( Express Checkout ) : ( Proceed to Checkout ) } User Onboarding tsxfunction Onboarding({ user }) { const { enabled: newOnboarding } = useFeatureFlag('new-onboarding-flow', { signup_date: user.signupDate, account_type: user.type })

return newOnboarding ? : } Feature Rollout tsxfunction BetaFeatures() { const { enabled: betaAccess } = useFeatureFlag('beta-program', { subscription_tier: 'enterprise', beta_opt_in: true })

if (!betaAccess) { return (

return } Building and Publishing Development bashnpm run dev # Watch mode npm run build # Production build npm run test # Run tests npm run lint # Lint code Publishing bashnpm run build npm publish Browser Support

Chrome/Edge 88+ Firefox 85+ Safari 14+ Node.js 16+

License MIT Support For questions and support, please refer to the main platform documentation or create an issue in the repository.