Skip to main content

EasyProvider

The EasyProvider is the main provider component that initializes the Easy SDK and secure form elements. It must wrap your application to enable Easy SDK functionality.

Props​

interface EasyProviderProps {
  apiKey: string; // Your Easy API key (required)
  __dev?: boolean; // Enable development/sandbox mode (optional)
  children: React.ReactNode; // Child components
}

apiKey (required)​

Your Easy publishable API key. This should be stored in environment variables.

Security

Never use your secret API key in client-side code! Always use the publishable key for the React SDK.

__dev (optional)​

Enables development/sandbox mode. Set to true in development environments.

children​

The React components that will have access to the Easy SDK through the useEasy hook.

Basic Usage​

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

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

export default App;
tip

For Next.js, use process.env.NEXT_PUBLIC_EASY_API_KEY instead.

With Development Mode​

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

function App() {
  return (
    <EasyProvider
      apiKey={import.meta.env.VITE_EASY_API_KEY}
      __dev={import.meta.env.DEV}
    >
      <YourApp />
    </EasyProvider>
  );
}

Environment Variables​

Vite​

Create a .env file:

VITE_EASY_API_KEY=your_publishable_key_here

Access it with import.meta.env.VITE_EASY_API_KEY.

Next.js​

Create a .env.local file:

NEXT_PUBLIC_EASY_API_KEY=your_publishable_key_here

Use it in your app:

<EasyProvider apiKey={process.env.NEXT_PUBLIC_EASY_API_KEY}>
  <App />
</EasyProvider>

Vite​

Create a .env file:

VITE_EASY_API_KEY=your_publishable_key_here

Use it in your app:

<EasyProvider apiKey={import.meta.env.VITE_EASY_API_KEY}>
  <App />
</EasyProvider>

Context Availability​

All components wrapped by EasyProvider can access the Easy SDK through the useEasy hook:

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

function PaymentForm() {
  // ✅ Works - inside EasyProvider
  const { checkout } = useEasy();

  return <form>{/* ... */}</form>;
}

function App() {
  return (
    <EasyProvider apiKey={import.meta.env.VITE_EASY_API_KEY}>
      <PaymentForm /> {/* Has access to useEasy */}
    </EasyProvider>
  );
}

Error Handling​

If apiKey is not provided, EasyProvider will throw an error:

// ❌ Error: apiKey is required
<EasyProvider>
  <App />
</EasyProvider>

// ✅ Correct
<EasyProvider apiKey="easy_pk_...">
  <App />
</EasyProvider>

Multiple Providers​

You generally only need one EasyProvider at the root of your application. However, you can use multiple providers if needed (e.g., for different API keys in different parts of your app):

function App() {
  return (
    <div>
      <EasyProvider apiKey={import.meta.env.VITE_EASY_API_KEY_1}>
        <Section1 />
      </EasyProvider>

      <EasyProvider apiKey={import.meta.env.VITE_EASY_API_KEY_2}>
        <Section2 />
      </EasyProvider>
    </div>
  );
}

Best Practices​

  1. Place at the root: Wrap your entire app at the highest level possible
  2. Use environment variables: Never hardcode API keys
  3. Single instance: One provider is usually sufficient
  4. Error boundaries: Consider wrapping with error boundaries for production
import { ErrorBoundary } from "react-error-boundary";
import { EasyProvider } from "@easylabs/react";

function App() {
  return (
    <ErrorBoundary fallback={<ErrorFallback />}>
      <EasyProvider apiKey={import.meta.env.VITE_EASY_API_KEY}>
        <YourApp />
      </EasyProvider>
    </ErrorBoundary>
  );
}
Next.js Users

For Next.js projects, use process.env.NEXT_PUBLIC_EASY_API_KEY instead.

Next Steps​