Next.js integration

A complete, runnable Next.js example lives at easy-sdk/examples/next-example. This page is a guided tour — it points to the most-relevant files in that example so you can see the SDK wired into a real project, not just isolated snippets.

Source code

Repository: itseasyco/easy-sdk
Path: examples/next-example

What this example covers

Wiring EasyProvider into the App Router via a "use client" boundary, so server components above it stay server-side.
A storefront landing page that fetches products through a server action and renders an interactive grid.
A full checkout page (/checkout) that supports anonymous shoppers (creates a customer mid-flow), authenticated shoppers (uses a saved identity_id), and either a new card / bank account or a previously saved payment instrument.
A user profile (/profile) that lists the signed-in customer's orders, payment methods, and subscriptions through useEasy().getCustomerOrders / getCustomerPaymentInstruments / getCustomerSubscriptions.
An admin area (/admin) for products, prices, orders, subscriptions, and refunds — backed by Easy Labs server-side calls in Next.js Server Actions.
Mixed usage of @easylabs/react (client-side, for tokenization) and @easylabs/node (server-side, in actions).

Key files

File	What it shows
`src/components/Providers.tsx`	`"use client"` wrapper that renders `<EasyProvider>` from `process.env.NEXT_PUBLIC_EASY_API_KEY`.
`src/app/layout.tsx`	Root layout that mounts `<Providers>` once for the whole app.
`src/app/checkout/page.tsx`	Full client-side checkout flow with `useEasy().checkout`, branching on `customer_creation` vs. `identity_id`, plus existing-instrument selection.
`src/app/profile/page.tsx`	Customer dashboard fetching orders, payment instruments, and subscriptions via `useEasy()`.
`src/app/admin/products/actions.ts`	Server-side product CRUD in a Next.js Server Action using the Node SDK with React types imported for shape sharing.

Run it locally

git clone https://github.com/itseasyco/easy-sdk
cd easy-sdk
pnpm install
pnpm --filter @easylabs/common build
pnpm --filter @easylabs/react build
pnpm --filter @easylabs/node build

cd examples/next-example
cp .env.example .env.local
# Set NEXT_PUBLIC_EASY_API_KEY (sk_test_…), EASY_API_KEY (server-side), and DATABASE_URL.
pnpm db:gen
pnpm dev

Open http://localhost:3000.

The example uses Prisma for an embedded user / role / cart database — it is not part of the SDK and exists only to demonstrate the auth and admin flows in a realistic shape.

Adapting it

App Router only. EasyProvider must live inside a Client Component. The pattern in src/components/Providers.tsx is the recommended one — keep all client providers (theme, auth, cart, etc.) in a single file rendered from app/layout.tsx.
Pages Router. Mount <EasyProvider> once in pages/_app.tsx. No "use client" needed.
Server vs. client split. Use @easylabs/react only on the client (anywhere you need to tokenize a card or read live customer data with the user's session). Use @easylabs/node in server actions, route handlers, and webhooks where you need a server-side API key.
Strip auth. The example bundles a Prisma-backed auth system to show authenticated checkout — if you already have your own auth, replace useAuthContext() with your equivalent and pass user.customerId into checkout({ customer_creation: false, identity_id }).
Webhooks. Not in the example yet — see the Node SDK webhooks guide for the matching server side.