@unitpay/react

React SDK for UnitPay. Hooks, components, and a Next.js adapter for building billing UIs.

Installation

npm install @unitpay/react react @tanstack/react-query
# or
bun add @unitpay/react react @tanstack/react-query

Quick Start

import { UnitPayProvider, useCustomer, FeatureGate } from '@unitpay/react';

function App() {
  return (
    <UnitPayProvider publishableKey="upay_pk_..." customerId="cus_...">
      <Dashboard />
    </UnitPayProvider>
  );
}

function Dashboard() {
  const { customer, check } = useCustomer();
  const { allowed } = check('advanced-analytics');

  return (
    <div>
      <h1>Welcome, {customer?.name}</h1>
      <FeatureGate featureSlug="export-csv" fallback={<UpgradePrompt />}>
        <ExportButton />
      </FeatureGate>
    </div>
  );
}

Hooks

| Hook | Purpose | |------|---------| | useCustomer() | Customer data + entitlement check function | | useBilling() | All-in-one: customer, subscriptions, invoices, payment methods | | useEntitlement(slug) | Generic entitlement for a feature | | useBooleanEntitlement(slug) | Boolean feature flag | | useMeteredEntitlement(slug) | Usage-based with balance/limit/percentage | | useCreditEntitlement(slug) | Credit-based entitlement | | useConfigEntitlement(slug) | Config value entitlement | | useEnumEntitlement(slug) | Enum value entitlement | | useSubscriptions() | List subscriptions | | useSubscription(id) | Single subscription + cancel/resume/pause | | useInvoices() | List invoices | | usePaymentMethods() | List payment methods | | usePlans() | Public plans (no auth required) | | useCheckout() | Checkout session creation | | useUsageMeter(metricId) | Usage meter for a specific metric |

Components

FeatureGate

Declarative access control:

<FeatureGate
  featureSlug="premium-feature"
  fallback={<p>Upgrade to access this feature</p>}
  loading={<Spinner />}
  onDenied={(reason) => analytics.track('feature_gated', { reason })}
>
  <PremiumContent />
</FeatureGate>

Dev Mode

Zero API calls for local development and Storybook:

<UnitPayProvider
  devMode
  mockData={{
    customer: { id: 'cus_mock', name: 'Test User', email: '[email protected]' },
    entitlements: {
      'premium': { type: 'boolean', access: true },
      'api-calls': { type: 'metered', access: true, balance: 800, usage: 200, limit: 1000, isUnlimited: false },
    },
  }}
>
  <App />
</UnitPayProvider>

Next.js Adapter

Proxy API requests through your Next.js backend to keep the secret key server-side:

// app/api/unitpay/[...path]/route.ts
import { createUnitPayRouteHandler } from '@unitpay/react/next';

const handler = createUnitPayRouteHandler({
  secretKey: process.env.UNITPAY_SECRET_KEY!,
  apiBaseUrl: 'https://api.unitpay.dev/v1',
});

export { handler as GET, handler as POST, handler as PUT, handler as PATCH, handler as DELETE };

Then configure the provider to use the proxy:

<UnitPayProvider
  publishableKey="upay_pk_..."
  customerId="cus_..."
  proxyBaseUrl="/api/unitpay"
>
  <App />
</UnitPayProvider>

License

MIT