React hooks and provider for Subscribe.dev - Build AI-powered applications with integrated authentication, billing, storage, and 100+ curated AI models.

Installation

npm install @subscribe.dev/react
# or
yarn add @subscribe.dev/react
# or
bun add @subscribe.dev/react

Peer Dependencies

npm install react @clerk/clerk-react @tanstack/react-query

React: ^18.0.0 || ^19.0.0
@clerk/clerk-react: ^4.0.0 || ^5.0.0 (for authentication)
@tanstack/react-query: ^5.0.0 (for query management)

Quick Start

import { SubscribeDevProvider, useSubscribeDev } from '@subscribe.dev/react';

function App() {
  return (
    <SubscribeDevProvider
      projectToken="pub_your_project_token_here"
      clerkPublishableKey="pk_your_clerk_key_here"
    >
      <AIApplication />
    </SubscribeDevProvider>
  );
}

function AIApplication() {
  const { isSignedIn, client, subscribe } = useSubscribeDev();
  
  if (!isSignedIn) {
    return <div>Please sign in to continue</div>;
  }

  const generateContent = async () => {
    const result = await client.run("black-forest-labs/flux-schnell", {
      input: { prompt: "A beautiful landscape" }
    });
    console.log(result.output);
  };

  return (
    <div>
      <button onClick={generateContent}>Generate Image</button>
      <button onClick={subscribe}>Manage Subscription</button>
    </div>
  );
}

Use Cases

Multi-Model AI Applications

Build applications that leverage multiple AI models for rich, interactive experiences:

function MultiModalApp() {
  const { client, isSignedIn } = useSubscribeDev();
  const [image, setImage] = useState(null);
  const [description, setDescription] = useState('');

  const handleGenerate = async (prompt) => {
    if (!isSignedIn || !client) return;

    try {
      // Generate image and description in parallel
      const [imageResult, textResult] = await Promise.all([
        client.run("black-forest-labs/flux-schnell", {
          input: { prompt, width: 1024, height: 1024 }
        }),
        client.run("anthropic/claude-3-haiku", {
          input: { 
            messages: [{ 
              role: "user", 
              content: `Describe what an image with this prompt would look like: "${prompt}"` 
            }] 
          }
        })
      ]);

      setImage(imageResult.output[0]);
      setDescription(textResult.output);
    } catch (error) {
      console.error('Generation failed:', error);
    }
  };

  return (
    <div>
      <GenerateInput onGenerate={handleGenerate} />
      <ImageDisplay src={image} />
      <TextDisplay content={description} />
    </div>
  );
}

Persistent User Storage

Store user preferences, application state, and session data with automatic cloud synchronization:

function UserPreferencesApp() {
  const { useStorage, useUsage } = useSubscribeDev();
  const [preferences, setPreferences, syncStatus] = useStorage('user-prefs', {
    theme: 'light',
    favoriteModels: [],
    generationHistory: []
  });
  const { allocatedCredits, usedCredits, remainingCredits } = useUsage();

  const addToHistory = (result) => {
    setPreferences({
      ...preferences,
      generationHistory: [result, ...preferences.generationHistory].slice(0, 50)
    });
  };

  const toggleTheme = () => {
    setPreferences({
      ...preferences,
      theme: preferences.theme === 'light' ? 'dark' : 'light'
    });
  };

  return (
    <div>
      <div>Sync Status: {syncStatus}</div>
      <div>Credits remaining: {remainingCredits}</div>
      <button onClick={toggleTheme}>
        Switch to {preferences.theme === 'light' ? 'dark' : 'light'} theme
      </button>
      <HistoryList items={preferences.generationHistory} />
    </div>
  );
}

Real-time Gallery Applications

Build gallery applications with persistent storage and cross-device synchronization:

function GalleryApp() {
  const { client, useStorage } = useSubscribeDev();
  const [images, setImages, syncStatus] = useStorage('image-gallery', []);
  const [loading, setLoading] = useState(false);

  const generateAndStore = async (prompt) => {
    setLoading(true);
    try {
      const result = await client.run("stability-ai/sdxl", {
        input: { prompt }
      });

      const newImage = {
        id: crypto.randomUUID(),
        url: result.output[0],
        prompt,
        timestamp: Date.now(),
        model: "stability-ai/sdxl"
      };

      // Add to gallery and keep latest 100 images
      setImages([newImage, ...images].slice(0, 100));
    } finally {
      setLoading(false);
    }
  };

  return (
    <div>
      <GenerateInput onGenerate={generateAndStore} loading={loading} />
      <div>Gallery sync: {syncStatus}</div>
      <ImageGrid images={images} />
    </div>
  );
}

Subscription-Gated Features

Implement premium features with built-in subscription management:

function PremiumFeatures() {
  const { subscribe, client } = useSubscribeDev();
  const { isSubscribed, subscriptionStatus } = useSubscribeDevAuth();

  const runPremiumModel = async () => {
    if (!isSubscribed) {
      subscribe(); // Opens subscription modal
      return;
    }

    const result = await client.run("premium-model/advanced", {
      input: { /* premium model parameters */ }
    });
    
    return result.output;
  };

  return (
    <div>
      {isSubscribed ? (
        <div>
          <p>Plan: {subscriptionStatus.plan?.name}</p>
          <button onClick={runPremiumModel}>Use Premium Model</button>
        </div>
      ) : (
        <div>
          <p>Upgrade to access premium models</p>
          <button onClick={subscribe}>Subscribe Now</button>
        </div>
      )}
    </div>
  );
}

Cost-Aware Applications

Build applications that monitor and display usage costs in real-time:

function CostAwareApp() {
  const { client } = useSubscribeDev();
  const [balance, setBalance] = useState(null);
  const [transactions, setTransactions] = useState([]);

  useEffect(() => {
    const loadBalanceAndHistory = async () => {
      const [balanceInfo, history] = await Promise.all([
        client.getBalance(),
        client.getTransactions({ limit: 10 })
      ]);
      
      setBalance(balanceInfo);
      setTransactions(history.transactions);
    };

    loadBalanceAndHistory();
  }, [client]);

  const generateWithCostTracking = async (prompt) => {
    const beforeBalance = await client.getBalance();
    
    const result = await client.run("expensive-model/high-quality", {
      input: { prompt }
    });
    
    const afterBalance = await client.getBalance();
    const cost = beforeBalance.remainingCredits - afterBalance.remainingCredits;
    
    console.log(`Generation cost: ${cost} credits`);
    return result;
  };

  return (
    <div>
      <div>
        Remaining Credits: {balance?.remainingCredits || 0}
      </div>
      <RecentTransactions transactions={transactions} />
      <GenerateButton onGenerate={generateWithCostTracking} />
    </div>
  );
}

Usage Monitoring & Analytics

Track comprehensive usage metrics including credits, rate limits, and consumption patterns:

function UsageAnalytics() {
  const { useUsage } = useSubscribeDev();
  const { allocatedCredits, usedCredits, remainingCredits, loading, error, refreshUsage } = useUsage();

  if (loading) return <div>Loading usage data...</div>;
  if (error) return <div>Error: {error}</div>;

  const creditUtilization = allocatedCredits > 0 ? (usedCredits / allocatedCredits) * 100 : 0;

  return (
    <div className="usage-dashboard">
      <div className="usage-header">
        <h2>Usage Analytics</h2>
        <button onClick={refreshUsage}>Refresh</button>
      </div>

      {/* Credit Information */}
      <div className="credits-section">
        <h3>Credits</h3>
        <div className="credit-stats">
          <div>Allocated: {allocatedCredits}</div>
          <div>Used: {usedCredits}</div>
          <div>Remaining: {remainingCredits}</div>
          <div>Utilization: {creditUtilization.toFixed(1)}%</div>
        </div>
    </div>
  );
}

Error Handling & User Feedback

Implement comprehensive error handling with user-friendly feedback:

function RobustApp() {
  const { client } = useSubscribeDev();
  const [error, setError] = useState(null);
  const [loading, setLoading] = useState(false);

  const handleGenerate = async (prompt) => {
    setError(null);
    setLoading(true);

    try {
      const result = await client.run("model-name", {
        input: { prompt }
      });
      return result.output;
    } catch (err) {
      if (err.name === 'InsufficientBalanceError') {
        setError('Not enough credits. Please upgrade your plan.');
      } else if (err.name === 'RateLimitError') {
        setError(`Rate limited. Try again in ${err.retryAfter} seconds.`);
      } else if (err.name === 'ValidationError') {
        setError('Invalid input. Please check your prompt.');
      } else {
        setError('Generation failed. Please try again.');
      }
    } finally {
      setLoading(false);
    }
  };

  return (
    <div>
      <GenerateInput onGenerate={handleGenerate} loading={loading} />
      {error && <ErrorMessage message={error} />}
    </div>
  );
}

Advanced Client Features

Access the full Subscribe.dev client API for advanced use cases:

function AdvancedApp() {
  const { client } = useSubscribeDev();

  // Monitor rate limits
  const checkRateLimits = async () => {
    const limits = await client.getRateLimits();
    console.log('Concurrent requests:', limits.concurrent.currentRequests);
    console.log('Hourly limit reached:', !limits.hour?.allowed);
  };

  // Manage session data
  const syncSessionData = async () => {
    const sessionData = await client.getSessionData();
    await client.setStorage({
      ...sessionData,
      lastActivity: Date.now()
    });
  };

  // Get subscription details
  const checkSubscription = async () => {
    const subscription = await client.getSubscriptionStatus();
    if (subscription.hasActiveSubscription) {
      console.log('Plan:', subscription.plan?.name);
      console.log('Credits:', subscription.plan?.tokenLimit);
    }
  };

  return (
    <div>
      <button onClick={checkRateLimits}>Check Rate Limits</button>
      <button onClick={syncSessionData}>Sync Session</button>
      <button onClick={checkSubscription}>Check Subscription</button>
    </div>
  );
}

API Reference

SubscribeDevProvider

The main provider component that enables all Subscribe.dev functionality.

<SubscribeDevProvider
  projectToken="pub_your_project_token"     // Required: Your project API key
  clerkPublishableKey="pk_your_clerk_key"   // Required: Clerk authentication
  baseUrl="https://api.subscribe.dev"       // Optional: Custom API URL
>
  <YourApp />
</SubscribeDevProvider>

useSubscribeDev()

Main hook providing access to client, authentication, and storage.

const {
  client,              // SubscribeDevClient instance
  token,               // Current auth token
  isSignedIn,          // Authentication status
  subscribe,           // Open subscription modal
  useStorage,          // Storage hook factory
  useUsage             // Usage hook factory
} = useSubscribeDev();

useSubscribeDevAuth()

Authentication and subscription management.

const {
  isSignedIn,          // Authentication status
  isSubscribed,        // Subscription status
  subscribe,           // Open subscription modal
  subscriptionStatus,  // Detailed subscription info
  subscriptionLoading  // Loading state
} = useSubscribeDevAuth();

useStorage(key, initialValue)

Persistent storage with cloud synchronization.

const [value, setValue, syncStatus] = useStorage('storage-key', defaultValue);
// syncStatus: 'local' | 'syncing' | 'synced' | 'error'

useUsage()

Get user balance information including allocated, used, and remaining credits.

const { useUsage } = useSubscribeDev();
const { allocatedCredits, usedCredits, remainingCredits, loading, error, refreshUsage } = useUsage();
// allocatedCredits: number - Total credits allocated to user
// usedCredits: number - Credits consumed by user
// remainingCredits: number - Credits remaining for user
// loading: boolean - Loading state when fetching balance data
// error: string | null - Error message if fetch fails
// refreshUsage: () => Promise<void> - Manually refresh usage data

Client Methods

All Subscribe.dev client methods are available through the client object:

client.run(model, options) - Run AI models
client.getBalance() - Check credit balance
client.getTransactions(options) - Get usage history
client.getRateLimits() - Check rate limit status
client.getStorage(options) - Get user storage
client.setStorage(data, options) - Update user storage
client.getSubscriptionStatus() - Check subscription
client.getUsage() - Get comprehensive usage limits and consumption data

Authentication Components

Iframe-compatible Clerk components optimized for embedded applications:

import { SignIn, SignInButton, UserButton } from '@subscribe.dev/react';

// Full sign-in form
<SignIn />

// Sign-in trigger button
<SignInButton>Sign In</SignInButton>

// User profile menu
<UserButton />

Type Definitions

type SyncStatus = 'local' | 'syncing' | 'synced' | 'error';

interface SubscribeDevContextValue {
  client: SubscribeDevClient | null;
  token: string | null;
  isSignedIn: boolean;
  subscribe: () => void;
  useStorage: <T>(key: string, initialValue: T) => [T, (value: T) => void, SyncStatus];
}

Best Practices

Error Handling: Always wrap AI calls in try-catch blocks
Loading States: Provide loading indicators for better UX
Cost Awareness: Monitor credits and inform users of costs
Storage Sync: Check sync status for critical data operations
Rate Limiting: Handle rate limit errors gracefully
Subscription Gates: Use subscription status to control feature access

Requirements

Node.js: >=18
React: ^18.0.0 || ^19.0.0
TypeScript: ^5.0.0 (recommended)

License

MIT

Keywords

FAQs

Package last updated on 15 Aug 2025

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@subscribe.dev/react