React SDK

Microapp subscriptions for React apps.

The Payments SDK for React enables you to subscribe users using React-specific features.

Getting Started

1. Install the SDK

Install the SDK with your preferred package manager.

npm

npm install @microapp-io/react

2. Wrap Your App with the Provider

In order for your microapp to have access to payments features, it needs to be wrapped in the SubscriptionProvider component:

import { SubscriptionProvider } from "@microapp-io/react";

function App() {
  return <SubscriptionProvider>{/* Your microapp code here */}</SubscriptionProvider>;
}

For local development, we recommend using the sandbox feature on the SubscriptionProvider component to return mocked subscriptions:

import { SubscriptionProvider, MicroappSubscriptionPlanCycle } from "@microapp-io/react";

const sandbox = {
  enabled: process.env.NODE_ENV !== "production",
  subscription: () => ({
    id: 'some-subscription-id',
    appId: 'some-app-id',
    user: {
      id: 'some-user-id',
      email: '[e-mail]',
      name: 'FirstName LastName',
    },
    active: true,
    subscriptionPlan: {
      id: 'some-subscription-plan-id',
      name: 'free',
      priceInCents: 0,
      cycle: MicroappSubscriptionPlanCycle.ONE_TIME,
      features: [
        {
          name: 'some-feature-name',
          description: 'some-feature-description'
        },
      ],
      createdAt: new Date(),
      updatedAt: new Date(),
    },
    createdAt: new Date(),
    updatedAt: new Date(),
  }),
};

function App() {
  return (
    <SubscriptionProvider sandbox={sandbox}>
      {/* Your microapp code here */}
    </SubscriptionProvider>
  );
}

The sandbox prop should only be used for local development. Do not use it in production.

3. Use the useSubscription Hook

The useSubscription hook returns all of the payments data and methods available to your microapp. It returns the following type:

type Payments = {
  hasSubscribed: boolean;
  isLoading: boolean;
  subscription?: {
    id: string;
    appId: string;
    user: {
      id: string;
      name: string;
    };
    active: boolean;
    subscriptionPlan: {
      id: string;
      name: string;
      description?: string;
      priceInCents: number;
      cycle: MicroappSubscriptionPlanCycle;
      features: Array<{
        id: string;
        name: string;
        description?: string;
      }>;
      createdAt: Date;
      updatedAt: Date;
      archivedAt?: Date;
    };
    paymentsProvider?: string;
    paymentsSubscriptionManagementUrl?: string;
    paymentsSubscriptionId?: string;
    paymentsPaymentId?: string;
    createdAt: Date;
    updatedAt: Date;
    cancelledAt?: Date;
    endsAt?: Date;
  };
  error?: Error;
  requireSubscription: () => void;
};

4. Prompt the User to Subscribe

You can prompt the user to subscribe by calling the requireSubscription method.

import { useSubscription } from '@microapp-io/react';

function Home() {
  const { requireSubscription } = useSubscription();

  return (
    <button onClick={() => requireSubscription()}>Subscribe</button>
  );
}

5. Get Notified when the User subscribes

You can get notified when the user subscribes or changes the subscription passing a callback on Payments initialization

  import { useSubscription } from '@microapp-io/react';

  function Home() {
    const { requireSubscription } = useSubscription({
      onChange: (userSubscription) => console.log('User subscribed', userSubscription),
    });

    requireSubscription();
  }

6. Example Usage

Here is an example of how you can use the useSubscription hook in your microapp:

import { useSubscription } from "@microapp-io/react";

function Home() {
  const {
    hasSubscribed,
    isLoading,
    subscription,
    error,
    requireSubscription,
  } = useSubscription({
    onChange: (userSubscription) => console.log('User subscribed', userSubscription),
  });

  if (isLoading) {
    return <p>Loading...</p>;
  }

  if (error) {
    return <p>Error: {error.message}</p>;
  }

  if (!hasSubscribed) {
    return <button onClick={() => requireSubscription()}>Subscribe</button>;
  }
}