Installation

Prerequisites

• Node.js 22 or later (matches the engines.node constraint in the package).
• React 18 or 19. react and react-dom are peer dependencies.
• A bundler that supports ES modules. Vite, Next.js, Remix, Webpack 5, and Rspack all work without configuration.
• An Easy Labs publishable API key. Test keys are prefixed with sk_test_ and route to the sandbox environment automatically; live keys route to production.

Install the package

npm install @easylabs/react react react-dom

pnpm add @easylabs/react react react-dom

yarn add @easylabs/react react react-dom

bun add @easylabs/react react react-dom

The package is published as a dual ESM/CJS module with TypeScript declarations and is side-effect-free, so unused exports tree-shake cleanly.

Verify the install

Wrap your app in EasyProvider and exercise the SDK with a real call — EasyProvider runs key validation and Basis Theory session setup in an effect and swallows any failure (it logs EasyProvider initialization failed: to the console but the component still mounts). A successful mount alone does not prove the SDK is wired up; you need to either watch the console or, better, trigger an API call (e.g. getProducts()) or a tokenization attempt.

import { EasyProvider, useEasy } from "@easylabs/react";

function StatusCheck() {
  const { getProducts } = useEasy();
  return <button onClick={() => getProducts().then(console.log)}>Ping</button>;
}

export default function App() {
  return (
    <EasyProvider apiKey={import.meta.env.VITE_EASY_API_KEY}>
      <StatusCheck />
    </EasyProvider>
  );
}

Open the browser console and click Ping — you should see an ApiResponse<ProductData[]> payload. If apiKey is missing or invalid, EasyProvider logs EasyProvider initialization failed: and useEasy calls that depend on tokenization (e.g. checkout, createPaymentInstrument) will throw.

Next steps

• Quickstart — render your first payment.
• EasyProvider — the SDK's entry point.