Quickstart
Add CKB KeyWay to a React or Next.js application.
1. Install the SDK
npm install @ckb-keyway/react2. Register your application
Open the KeyWay developer console, create an application, and add every exact browser origin that will use it. Add local development origins separately from production origins, then copy the public app ID.
3. Add the provider
Render KeyWayProvider in a client component above every component that uses KeyWay.
"use client";
import { KeyWayProvider } from "@ckb-keyway/react";
export function Providers({ children }: { children: React.ReactNode }) {
return (
<KeyWayProvider appId="keyway_..." appName="Acme Pay" theme="light">
{children}
</KeyWayProvider>
);
}import { Providers } from "./providers";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body><Providers>{children}</Providers></body>
</html>
);
}4. Add login and wallet state
"use client";
import { KeyWayLoginButton, useKeyWay, useCkbWallet, useFiber } from "@ckb-keyway/react";
export function Wallet() {
const { ready, authenticated } = useKeyWay();
const account = useCkbWallet();
const fiber = useFiber();
if (!ready) return <p>Loading login...</p>;
return (
<section>
<KeyWayLoginButton />
{authenticated && account.status === "loading" ? <p>Loading wallet...</p> : null}
{account.address ? <p>CKB address: {account.address}</p> : null}
{account.status === "ready" && fiber.status !== "running" ? (
<button disabled={fiber.status === "starting"} onClick={() => void fiber.start().catch(() => undefined)}>
{fiber.status === "starting" ? "Starting Fiber..." : "Start Fiber"}
</button>
) : null}
{account.error || fiber.error ? <p role="alert">{(account.error ?? fiber.error)?.message}</p> : null}
</section>
);
}Login recovers the CKB account without starting Fiber. Calling start() from useFiber() starts the user's Fiber node, or connects to it when it's hosted; it does not fund a channel. Set autoStartFiber to start Fiber as soon as the user signs in, or use KeyWayFiberButton. The hosted node, the default, needs no cross-origin isolation headers.
The app ID is public. It identifies the integration and lets KeyWay enforce its registered origins; it is not a secret credential.
5. Open the application
Select Log in, enter an email address, and submit the six-digit code. The same email recovers the same CKB account.
Optional browser node
Set fiberNode="browser" on the provider to run the user's Fiber node in the page, as WebAssembly. This requires cross-origin isolation. For Next.js, add these response headers in next.config.ts:
export default {
async headers() {
return [{
source: "/(.*)",
headers: [
{ key: "Cross-Origin-Opener-Policy", value: "same-origin" },
{ key: "Cross-Origin-Embedder-Policy", value: "require-corp" },
],
}];
},
};For Vite, configure the same headers under server.headers for local development and on your production host. Verify window.crossOriginIsolated === true before startup. Browser state moves between devices only after a successful explicit logout backup. Browser and hosted nodes are separate nodes, so switching between them doesn't move channels.
Cross-origin wallet windows stop working
Cross-Origin-Opener-Policy: same-origin cuts the link between your page and any window it opens on another site. JoyID, EVM wallet sites, and sign-in or payment windows from other sites can't send their result back, and your page sees the window as closed at once. KeyWay's own JoyID backups handle this: on a cross-origin isolated page they switch to a window on your site, or a full-page redirect, by themselves (Account recovery). Anything else of yours that opens such a window needs its own redirect flow, or a page without these headers.
Next: Fiber payments
Open a channel and make the account ready to send and receive.