name: flowglad-feature-gating
description: Implement feature access checks using Flowglad to gate premium features, create paywalls, and restrict functionality based on subscription status. Use this skill when adding paid-only features or checking user entitlements.
license: MIT
metadata:
author: flowglad
version: "1.0.0"

Feature Gating

Abstract

Implement feature access checks using Flowglad's checkFeatureAccess method to gate premium features, create paywalls, and restrict functionality based on subscription status.

Table of Contents

1. Loading State Handling — CRITICAL
2. 1.1 Wait for Billing to Load
3. 1.2 Skeleton Loading Patterns
4. Server-Side Gating — HIGH
5. 2.1 Verify Access on Server
6. 2.2 API Route Protection
7. Feature Identification — MEDIUM
8. 3.1 Use Slugs Not IDs
9. Component Wrapper Patterns — MEDIUM
10. 4.1 Feature Gate Component
11. 4.2 Higher-Order Component Pattern
12. Redirect to Upgrade Patterns — MEDIUM
13. 5.1 Client-Side Redirect
14. 5.2 Server-Side Redirect

1. Loading State Handling

Impact: CRITICAL

The billing hook loads asynchronously. While loading, checkFeatureAccess is null (not a function). If you try to call it before loading completes, you'll get a runtime error or incorrect behavior. This causes premium users to see upgrade prompts or paywalls incorrectly.

Note: The flowglad() factory function used in server-side examples must be set up in your project (typically at @/lib/flowglad). See the setup skill for configuration instructions.

1.1 Wait for Billing to Load

Impact: CRITICAL (prevents flash of incorrect content)

Users with active subscriptions will see upgrade prompts flash briefly if you don't wait for billing to load before checking access.

Incorrect: checks access before billing loads

function PremiumFeature() {
  const { checkFeatureAccess } = useBilling()

  // BUG: checkFeatureAccess is null while loading!
  // This will throw: "checkFeatureAccess is not a function"
  if (!checkFeatureAccess('premium-feature')) {
    return <UpgradePrompt />
  }

  return <PremiumContent />
}

This crashes because checkFeatureAccess is null until billing data loads, not a callable function.

Correct: check both loaded and checkFeatureAccess

function PremiumFeature() {
  const { loaded, checkFeatureAccess } = useBilling()

  if (!loaded || !checkFeatureAccess) {
    return <LoadingSkeleton />
  }

  if (!checkFeatureAccess('premium-feature')) {
    return <UpgradePrompt />
  }

  return <PremiumContent />
}

Always check both loaded and checkFeatureAccess before calling the function to ensure billing data is available.

1.2 Skeleton Loading Patterns

Impact: CRITICAL (prevents layout shift)

Show appropriate loading states that match the expected content dimensions to prevent layout shift.

Incorrect: shows nothing or spinner

function Dashboard() {
  const { loaded, checkFeatureAccess } = useBilling()

  if (!loaded) {
    return null // Content disappears!
  }

  return <DashboardContent />
}

Correct: show skeleton matching content layout

function Dashboard() {
  const { loaded, checkFeatureAccess } = useBilling()

  if (!loaded || !checkFeatureAccess) {
    return (
      <div className="space-y-4">
        <div className="h-8 w-48 bg-gray-200 animate-pulse rounded" />
        <div className="h-64 bg-gray-200 animate-pulse rounded" />
      </div>
    )
  }

  return <DashboardContent />
}

2. Server-Side Gating

Impact: HIGH

Client-side feature checks are for UI purposes only. Any sensitive operation or data access must verify subscription status server-side. Users can bypass client-side checks by modifying frontend code or using browser developer tools.

2.1 Verify Access on Server

Impact: HIGH (security requirement)

Never trust client-side access checks for operations that cost money, access sensitive data, or perform privileged actions.

Incorrect: trusts client-side check for sensitive operation

// API route
export async function POST(req: Request) {
  // Client could bypass this by modifying frontend code
  const { hasAccess } = await req.json()
  if (!hasAccess) {
    return Response.json({ error: 'No access' }, { status: 403 })
  }
  return performSensitiveOperation()
}

Correct: verify server-side

// API route
import { flowglad } from '@/lib/flowglad'
import { auth } from '@/lib/auth'

export async function POST(req: Request) {
  const session = await auth()
  if (!session?.user?.id) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 })
  }

  const billing = await flowglad(session.user.id).getBilling()

  if (!billing.checkFeatureAccess('api-access')) {
    return Response.json({ error: 'Upgrade required' }, { status: 403 })
  }

  return performSensitiveOperation()
}

2.2 API Route Protection

Impact: HIGH (prevents unauthorized access)

Create a reusable pattern for protecting multiple API routes with feature checks.

Incorrect: duplicates check logic everywhere

// routes/generate.ts
export async function POST(req: Request) {
  const session = await auth()
  const billing = await flowglad(session.user.id).getBilling()
  if (!billing.checkFeatureAccess('ai-generation')) {
    return Response.json({ error: 'Upgrade required' }, { status: 403 })
  }
  // ... generation logic
}

// routes/export.ts
export async function POST(req: Request) {
  const session = await auth()
  const billing = await flowglad(session.user.id).getBilling()
  if (!billing.checkFeatureAccess('export')) {
    return Response.json({ error: 'Upgrade required' }, { status: 403 })
  }
  // ... export logic
}

Correct: create reusable middleware/helper

// lib/requireFeature.ts
import { flowglad } from '@/lib/flowglad'
import { auth } from '@/lib/auth'

export async function requireFeature(featureSlug: string) {
  const session = await auth()
  if (!session?.user?.id) {
    return { error: 'Unauthorized', status: 401 }
  }

  const billing = await flowglad(session.user.id).getBilling()

  if (!billing.checkFeatureAccess(featureSlug)) {
    return { error: 'Upgrade required', status: 403 }
  }

  return { userId: session.user.id, billing }
}

// routes/generate.ts
export async function POST(req: Request) {
  const result = await requireFeature('ai-generation')
  if ('error' in result) {
    return Response.json({ error: result.error }, { status: result.status })
  }

  const { userId, billing } = result
  // ... generation logic
}

3. Feature Identification

Impact: MEDIUM

How you reference features affects code maintainability and environment portability.

3.1 Use Slugs Not IDs

Impact: MEDIUM (environment portability)

Feature IDs are auto-generated and differ between development, staging, and production environments. Slugs are stable identifiers you control.

Incorrect: hardcoding Flowglad IDs

// IDs change between environments!
if (billing.checkFeatureAccess('feat_abc123xyz')) {
  // Works in dev, breaks in production
}

Correct: use slugs

// Slugs are stable across environments
if (billing.checkFeatureAccess('advanced-analytics')) {
  // Works everywhere
}

Define feature slugs in your Flowglad dashboard and reference them consistently in code.

4. Component Wrapper Patterns

Impact: MEDIUM

Reusable patterns for gating components reduce boilerplate and ensure consistent behavior.

4.1 Feature Gate Component

Impact: MEDIUM (reduces boilerplate)

Create a declarative component for gating content.

Incorrect: repeats gate logic in every component

function AnalyticsDashboard() {
  const { loaded, checkFeatureAccess } = useBilling()

  if (!loaded || !checkFeatureAccess) return <Skeleton />
  if (!checkFeatureAccess('analytics')) return <UpgradePrompt feature="analytics" />

  return <Analytics />
}

function ExportButton() {
  const { loaded, checkFeatureAccess } = useBilling()

  if (!loaded || !checkFeatureAccess) return <Skeleton />
  if (!checkFeatureAccess('export')) return <UpgradePrompt feature="export" />

  return <ExportUI />
}

Correct: create reusable FeatureGate component

// components/FeatureGate.tsx
import { useBilling } from '@flowglad/nextjs'
import { ReactNode } from 'react'

interface FeatureGateProps {
  feature: string
  children: ReactNode
  fallback?: ReactNode
  loading?: ReactNode
}

export function FeatureGate({
  feature,
  children,
  fallback = <UpgradePrompt />,
  loading = <Skeleton />,
}: FeatureGateProps) {
  const { loaded, checkFeatureAccess } = useBilling()

  if (!loaded || !checkFeatureAccess) {
    return <>{loading}</>
  }

  if (!checkFeatureAccess(feature)) {
    return <>{fallback}</>
  }

  return <>{children}</>
}

// Usage
function AnalyticsDashboard() {
  return (
    <FeatureGate feature="analytics">
      <Analytics />
    </FeatureGate>
  )
}

function ExportButton() {
  return (
    <FeatureGate feature="export" fallback={<LockedExportButton />}>
      <ExportUI />
    </FeatureGate>
  )
}

4.2 Higher-Order Component Pattern

Impact: MEDIUM (alternative pattern for class components or full-page gates)

Use HOC pattern when you need to gate entire pages or components.

Incorrect: duplicates page-level checks

// pages/analytics.tsx
export default function AnalyticsPage() {
  const { loaded, checkFeatureAccess } = useBilling()

  if (!loaded || !checkFeatureAccess) return <PageSkeleton />
  if (!checkFeatureAccess('analytics')) {
    // Using redirect() in a client component - this won't work!
    redirect('/pricing')
    return null
  }

  return <AnalyticsDashboard />
}

Correct: create withFeatureAccess HOC

'use client'

// lib/withFeatureAccess.tsx
import { useEffect } from 'react'
import { useRouter } from 'next/navigation'
import { useBilling } from '@flowglad/nextjs'
import { ComponentType } from 'react'

export function withFeatureAccess<P extends object>(
  WrappedComponent: ComponentType<P>,
  feature: string,
  redirectTo = '/pricing'
) {
  return function WithFeatureAccess(props: P) {
    const { loaded, checkFeatureAccess } = useBilling()
    const router = useRouter()

    useEffect(() => {
      if (loaded && checkFeatureAccess && !checkFeatureAccess(feature)) {
        router.push(redirectTo)
      }
    }, [loaded, checkFeatureAccess, router])

    if (!loaded || !checkFeatureAccess) {
      return <PageSkeleton />
    }

    if (!checkFeatureAccess(feature)) {
      // Show skeleton while redirecting
      return <PageSkeleton />
    }

    return <WrappedComponent {...props} />
  }
}

// Usage
function AnalyticsDashboard() {
  return <div>Analytics content</div>
}

export default withFeatureAccess(AnalyticsDashboard, 'analytics')

Note: For better UX without flash, prefer server-side gating (see Section 5.2) when possible.

5. Redirect to Upgrade Patterns

Impact: MEDIUM

When users lack access, redirect them to upgrade rather than showing error states.

5.1 Client-Side Redirect

Impact: MEDIUM (better UX than error states)

Redirect users to pricing/upgrade page when they try to access gated features.

Incorrect: shows error message

function PremiumPage() {
  const { loaded, checkFeatureAccess } = useBilling()

  if (!loaded || !checkFeatureAccess) return <Skeleton />

  if (!checkFeatureAccess('premium')) {
    return <div>Error: You don't have access to this feature</div>
  }

  return <PremiumContent />
}

Correct: redirect to upgrade with context

'use client'

import { useEffect } from 'react'
import { useRouter, usePathname } from 'next/navigation'
import { useBilling } from '@flowglad/nextjs'

function PremiumPage() {
  const { loaded, checkFeatureAccess } = useBilling()
  const router = useRouter()
  const pathname = usePathname()

  useEffect(() => {
    if (loaded && checkFeatureAccess && !checkFeatureAccess('premium')) {
      // Redirect with return URL so user comes back after upgrade
      router.push(`/pricing?upgrade=premium&returnTo=${encodeURIComponent(pathname)}`)
    }
  }, [loaded, checkFeatureAccess, router, pathname])

  if (!loaded || !checkFeatureAccess || !checkFeatureAccess('premium')) {
    return <Skeleton />
  }

  return <PremiumContent />
}

5.2 Server-Side Redirect

Impact: MEDIUM (prevents page flash)

For server components or middleware, check access server-side before rendering.

Incorrect: client-side check causes flash

// Page loads, then redirects - user sees flash
export default function PremiumPage() {
  return (
    <ClientSideGate feature="premium">
      <PremiumContent />
    </ClientSideGate>
  )
}

Correct: check in server component or middleware

// app/premium/page.tsx (Server Component)
import { redirect } from 'next/navigation'
import { auth } from '@/lib/auth'
import { flowglad } from '@/lib/flowglad'

export default async function PremiumPage() {
  const session = await auth()
  if (!session?.user?.id) {
    redirect('/login')
  }

  const billing = await flowglad(session.user.id).getBilling()

  if (!billing.checkFeatureAccess('premium')) {
    redirect('/pricing?upgrade=premium')
  }

  return <PremiumContent />
}

Or using middleware for multiple routes:

// middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

const PREMIUM_ROUTES = ['/analytics', '/export', '/api-access']

export async function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl

  // Check if this is a premium route
  if (PREMIUM_ROUTES.some((route) => pathname.startsWith(route))) {
    // Note: Full billing check requires server-side call
    // For middleware, you might check a session flag or JWT claim
    // set during login that indicates subscription tier
    const session = await getSession(request)

    if (!session?.isPremium) {
      return NextResponse.redirect(
        new URL(`/pricing?returnTo=${pathname}`, request.url)
      )
    }
  }

  return NextResponse.next()
}

export const config = {
  matcher: ['/analytics/:path*', '/export/:path*', '/api-access/:path*'],
}

Note: Full Flowglad billing checks in middleware require additional setup. For most cases, server component checks (pattern above) are simpler and recommended.