React

Install the React package:

npm install @guapocado/react

Wrap the part of the app that needs Guapocado state:

import { GuapocadoProvider } from "@guapocado/react";

export function App({ orgId, children }) {
  return (
    <GuapocadoProvider
      apiKey={import.meta.env.VITE_GUAPOCADO_CLIENT_KEY}
      customerId={orgId}
    >
      {children}
    </GuapocadoProvider>
  );
}

customerId can be a user ID, organization ID, team ID, workspace ID, project ID, or your own dedicated Guapocado customer ID.

Use the Guapocado client directly:

import { useGuapocado } from "@guapocado/react";

function AnalyticsButton() {
  const guap = useGuapocado();

  async function openAnalytics() {
    if (await guap.has("advanced-analytics")) {
      // open the feature
    }
  }

  return <button onClick={openAnalytics}>Open analytics</button>;
}

Or use the convenience hooks:

import { useEntitlement, useUsageBalance } from "@guapocado/react";

function UsageSummary() {
  const analytics = useEntitlement("advanced-analytics");
  const apiCalls = useUsageBalance("api-calls");

  return <span>{apiCalls.balance} API calls</span>;
}

@guapocado/react is client-focused. Server-side checks for route handlers, server actions, and SSR should use @guapocado/sdk today. A dedicated Next.js package will own Next-specific helpers.