@unifold/react-provider

Minimal React provider for Unifold SDKs. This package provides only the essential publishableKey context and QueryClient setup that is shared across all Unifold React-based SDKs.

Purpose

This package is designed to be the universal, minimal provider for:

• @unifold/connect-react - Full UI SDK with modal components
• @unifold/headless-react - Headless SDK with hooks only (coming soon)
• Any future React-based Unifold SDKs

Installation

npm install @unifold/react-provider
# or
pnpm add @unifold/react-provider

Note: This package is typically installed automatically as a dependency of @unifold/connect-react or @unifold/headless-react. You don't need to install it directly unless you're building a custom SDK.

Usage

Basic Setup

import { UnifoldProvider } from '@unifold/react-provider';

function App() {
  return (
    <UnifoldProvider publishableKey="pk_test_...">
      <YourApp />
    </UnifoldProvider>
  );
}

Using the Context

import { useUnifold } from '@unifold/react-provider';

function MyComponent() {
  const { publishableKey } = useUnifold();
  
  return <div>Connected with key: {publishableKey}</div>;
}

API

UnifoldProvider

The main provider component that wraps your application.

Props:

• publishableKey (required): Your Unifold API publishable key
• children (required): Your React components

useUnifold

Hook to access the Unifold context.

Returns:

• publishableKey: Your API key

Features

• ✅ QueryClient Setup: Automatically configures React Query for optimal performance
• ✅ API Key Validation: Validates publishable keys on mount
• ✅ SSR Support: Safe to use with server-side rendering
• ✅ TypeScript: Full type definitions included
• ✅ Ultra-Lightweight: Minimal bundle size (~2 KB)
• ✅ Zero Configuration: Only requires publishableKey

Design Philosophy

This package intentionally stays minimal and only handles:

1. publishableKey management
2. React Query setup
3. SSR-safe context

All SDK-specific configuration (apiUrl, defaultConfig, etc.) is handled by the higher-level packages (@unifold/connect-react, @unifold/headless-react) that wrap this provider.

Architecture

This package sits at the base of the Unifold React ecosystem:

@unifold/react-provider (this package)
  └─ publishableKey + QueryClient only

@unifold/connect-react
  ├─ Wraps: @unifold/react-provider
  ├─ Adds: apiUrl, appName, defaultConfig
  └─ Provides: UI components, modal flows

@unifold/headless-react (coming soon)
  ├─ Wraps: @unifold/react-provider
  ├─ Adds: apiUrl, custom config
  └─ Provides: Headless hooks, custom UI

License

MIT