Next.js — Plandalf docs

Use Plandalf in client-rendered parts of your Next.js app. Load the organization SDK with next/script, render normal React buttons with Plandalf attributes, and keep identity or API work on the server.

The SDK runs in the browser

Checkout buttons, inline mounts, and promo widgets are browser behavior. Server routes are useful for signing identity tokens or creating backend records, not for opening checkout frames.

The path

Load the SDK after hydration

Use next/script with afterInteractive in your root layout or the route that contains checkout.
Render one client-side buying action

Start with a normal button that has data-plandalf-present.
Move identity to the server

If checkout should know the logged-in customer, sign a JWT in a route handler or server action, then pass it to a client component.
Test mode before live traffic

Add data-plandalf-mode="test" or call present() with { mode: "test" } while validating the route.

App Router setup

Next.js checkout route

import Script from "next/script";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        {children}
        <Script
          src="https://acme.plandalf.com/js/plandalf-sdk.js"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

"use client";

export function BuyButton() {
  return (
    <button
      data-plandalf-present="pro-plan"
      data-plandalf-frame="slideout"
      data-plandalf-mode="test"
    >
      Buy Pro
    </button>
  );
}

// Server-only helper. Sign with your Plandalf API credentials.
export async function createPlandalfIdentity(user: {
  id: string;
  email: string;
}) {
  return signPlandalfJwt({
    external_id: user.id,
    email: user.email
  });
}

Programmatic checkout

Use direct SDK calls when a click needs app logic before checkout opens.

"use client";

export function UpgradeButton({ userJwt }: { userJwt?: string }) {
  async function upgrade() {
    const flow = plandalf.present("pro-plan", {
      user: userJwt,
      frame: "modal",
      mode: "test"
    });

    for await (const event of flow.events) {
      console.log(event.type);
    }

    await flow;
  }

  return <button onClick={upgrade}>Upgrade</button>;
}