@lumnsh/react
v0.1.2
Published
Lumn React SDK — provider-agnostic payment components and hooks
Maintainers
sherrythebestReadme
@lumnsh/react
Lumn React SDK — entitlements, pricing, and checkout components.
Installation
pnpm add @lumnsh/react @lumnsh/nodeLumnProvider
Wrap your app with LumnProvider. In Next.js App Router, add it to your root layout:
// app/layout.tsx
import { LumnProvider } from '@lumnsh/react';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html>
<body>
<LumnProvider apiKey={process.env.NEXT_PUBLIC_LUMN_PUBLISHABLE_KEY!} baseUrl="https://app.lumn.dev">
{children}
</LumnProvider>
</body>
</html>
);
}Place LumnProvider as close to the root as needed—it must wrap any component that uses useLumnContext, useEntitlements, useSubscriptions, usePricing, LumnGate, LumnCheckout, or LumnPricing.
Next.js App Router
All SDK components and hooks are client components ('use client'). Import them directly; no dynamic(..., { ssr: false }) needed.
// app/dashboard/page.tsx
'use client';
import { LumnGate, LumnPricing } from '@lumnsh/react';
export default function DashboardPage() {
return (
<>
<LumnGate feature="pro" customerId="cus_xxx" loadingFallback={<div>Loading…</div>}>
<ProFeature />
</LumnGate>
<LumnPricing customerId="cus_xxx" />
</>
);
}SSR behavior
| Component / Hook | SSR | Hydration |
|------------------|-----|-----------|
| LumnProvider | Renders children as-is | No API calls |
| LumnGate | Renders loadingFallback or null | useEffect fetches entitlement after mount; updates UI when result arrives |
| LumnPricing | Renders loadingComponent or "Loading…" | usePricing fetches products on mount |
| LumnCheckout | Renders placeholder | Checkout session created on user action |
| useEntitlements / useSubscriptions / usePricing | N/A (hooks) | Call API when invoked on the client |
LumnGate does not block SSR; it shows loadingFallback (or nothing) until the client hydrates and the entitlement API returns. Use loadingFallback to avoid layout shift.
Exports
- Provider:
LumnProvider,useLumnContext - Components:
LumnGate,LumnCheckout,LumnPricing - Hooks:
useEntitlements,useSubscriptions,useLumn(entitlements + subscriptions),usePricing