Vanilla JS integration

Use @easylabs/browser in a Vanilla JS project — guided tour of the example app.

A complete, runnable Vanilla JS example lives at easy-sdk/examples/vanilla. 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.

Branch note (pre-0.2.0): the file paths linked below reference the 0.2.0 example wiring (Elements + wallets) that ships with @easylabs/browser 0.2.0. Until that release lands on main, the linked files live on the feat/easy-browser-parity branch — replace /main/ with /feat/easy-browser-parity/ in any link below if it 404s. Once 0.2.0 merges, the main links resolve normally.

The example exercises every payment surface added in 0.2.0:

A custom card form built from mountCardNumberElement, mountCardExpirationDateElement, and mountCardVerificationCodeElement, then converted to a token via tokenize.
An Apple Pay button via createApplePayButton.
A Google Pay button via createGooglePayButton.

It is a Vite + TypeScript project (no framework), so it represents the "smallest possible" integration target for @easylabs/browser.

Source code

Repository: itseasyco/easy-sdk
Path: examples/vanilla

What this example covers

Feature	How it's wired
Client bootstrap	`await createEasyClient({ apiKey })` in `src/main.ts`. The API key is read from `import.meta.env.VITE_EASY_API_KEY`.
Custom card form	Three `mount*Element` calls bind iframes into `#card-number`, `#card-exp`, and `#card-cvc`. Each gets `classes: { focus, complete, invalid }` for live styling via the CSS in `src/style.css`.
Brand surfacing	`cardNumber.on("change", ...)` writes the detected brand onto a `data-brand` attribute — the integrator could feed this into a card-network logo.
Tokenization	A "Create token" button calls `tokenize({ cardNumber, cardExpiration, cardCvc })` and prints the resulting `{ id, type, fingerprint }` to a `<pre>`.
Apple Pay	`createApplePayButton` mounts into `#apple-pay-slot` with a `merchantSession` callback that POSTs to `/api/apple-pay/session` (your backend wires this to Apple's `paymentSession` endpoint).
Google Pay	`createGooglePayButton` mounts into `#google-pay-slot`. The button defers to `isReadyToPay` and only renders when the device supports it.
Graceful unavailability	If `apple.isAvailable` is false the slot renders a "not available in this browser" hint. Google Pay does the same on a short timer (its readiness flips async).

Key files

File	Demonstrates
`examples/vanilla/index.html`	Container markup for the card form and wallet slots. Also loads Apple's `apple-pay-sdk.js` and Google's `pay.js` — both wallets need their vendor SDKs present.
`examples/vanilla/src/main.ts`	App bootstrap: `createEasyClient`, three `mount*Element` calls, `tokenize`, plus both wallet button factories. The whole integration in one file.
`examples/vanilla/src/style.css`	Stripe-like state styling — `.el-host.is-focused`, `.is-complete`, `.is-invalid` paired with the `classes` option on each element.
`examples/vanilla/package.json`	Project manifest. Run `dev`, `build`, `preview` via the standard Vite scripts.
`examples/vanilla/tsconfig.json`	TypeScript config — minimum settings for Vite + ESM.

Run it locally

git clone https://github.com/itseasyco/easy-sdk.git
cd easy-sdk
pnpm install
pnpm --filter vanilla-example dev

Drop a sandbox key into examples/vanilla/.env.local:

VITE_EASY_API_KEY=sk_test_...

Vite will print a local URL (typically http://localhost:5173). Without the key the page still renders — the elements will surface an error event when they try to mount, so the surface is visible without paid setup.

To consume the SDK from your own project rather than the workspace, install it directly:

pnpm add @easylabs/browser

Adapting it

Drop the surfaces you don't need. The example wires all three (Embedded Checkout is shown elsewhere); strip the wallet sections if you only need a custom card form, or strip the card section if wallets are enough.
Add a backend. The browser SDK can't (and shouldn't) mint sessions on its own. Add a tiny server endpoint — Express, Hono, Cloudflare Worker, anything — that exchanges the token reference for a payment instrument or a checkout session.
Wire merchantSession for real. The example's merchantSession callback POSTs to /api/apple-pay/session. That endpoint must call Apple's paymentSession URL with your merchant identity certificate. Apple refuses to validate from the browser.
Move the API key out of source. Vite exposes import.meta.env.VITE_* variables at build time. Use VITE_EASY_API_KEY for the sandbox key in development; in production, mint sessions on your backend with sk_live_* and never ship that key to the browser.