@vocoweb/features

Production-ready feature gating and entitlement engine for B2B SaaS.

Overview

@vocoweb/features is the "Entitlement Engine" that connects Stripe Plans to Code. It eliminates spaghetti feature-flag logic by providing a simple, declarative way to gate features based on subscription plans.

Key Features:

• 🚪 Feature Gates - Simple React wrapper to show/hide features
• 💳 Stripe Integration - Automatic plan detection and caching
• ⚡ Zero API Calls - Instant feature checks via Stripe cache
• 📊 Upgrade Prompts - Built-in upgrade banners
• 🎯 Type-Safe - Full TypeScript support

Installation

npm install @vocoweb/features

Quick Start

Configuration

// vocoweb.config.ts
export const config = {
  features: {
    analytics: { tiers: ['pro', 'enterprise'] },
    'api-access': { tiers: ['pro', 'enterprise'] },
    'custom-domain': { tiers: ['enterprise'] },
    'priority-support': { tiers: ['enterprise'] },
  },
};

Client-Side (React)

import { VocoGate } from '@vocoweb/features/react';

export default function Dashboard() {
  return (
    <div>
      <h1>Dashboard</h1>
      
      <VocoGate 
        feature="analytics" 
        fallback={<UpgradeBanner feature="Analytics Dashboard" />}
      >
        <AnalyticsDashboard />
      </VocoGate>
      
      <VocoGate feature="api-access">
        <APIKeysSection />
      </VocoGate>
    </div>
  );
}

Server-Side

import { features } from '@vocoweb/features';

export async function GET(request: Request) {
  const user = await auth.requireUser(request);
  
  // Check feature access
  const hasAnalytics = await features.hasFeature(user.id, 'analytics');
  
  if (!hasAnalytics) {
    return Response.json(
      { error: 'Upgrade to Pro to access analytics' },
      { status: 402 }
    );
  }
  
  // Feature available, proceed
  const data = await getAnalyticsData(user.id);
  return Response.json(data);
}

// Or use requireFeature (throws error if not available)
export async function POST(request: Request) {
  const user = await auth.requireUser(request);
  await features.requireFeature(user.id, 'api-access');
  
  // Proceed with API key generation
}

API Reference

Server Methods

• hasFeature(userId, feature) - Check if user has feature access
• getAvailableFeatures(userId) - Get all features for user's plan
• requireFeature(userId, feature) - Throw error if feature not available

React Components

• <VocoGate feature="name" fallback={<Component />}> - Feature gate wrapper

Environment Variables

# Stripe (Required)
STRIPE_SECRET_KEY=sk_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_...

# Supabase (Required)
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

How It Works

1. User subscribes to a plan in Stripe
2. Plan metadata is synced to your database via webhooks
3. @vocoweb/features checks the cached subscription data
4. Feature gates show/hide content based on plan tier

No API calls during feature checks = instant performance

License

MIT © VocoWeb

Support

• Email: [email protected]
• Documentation: GitHub Wiki

Built with care by VocoWeb