Quickstart
A Next.js community app that greets the viewer by name.
Start from the template
The fastest path is the Planeward app template. It is a pnpm + Turborepo monorepo with:
apps/web: a Next.js app with the member experience (/experience), the staff dashboard (/dashboard), a webhook route and its own Drizzle schema for Postgres.packages/planeward: a React provider and hooks, plus server helpers (requireViewer,handlePlanewardWebhook) built on the SDK.packages/ui: shared shadcn/ui components.
The iframe handshake, token verification, webhooks and API client come from @planeward/sdk on npm.
You need Node 24+, pnpm and Docker.
During development, set the app's frame URLs to your dev server (http://localhost:3000/experience). Localhost URLs work in your own workspace only; see Testing your app. Webhooks still need a public HTTPS URL, so run a tunnel such as cloudflared or ngrok for the webhook URL.
Follow the template's README to run it, register it in Settings › Apps › Developer and install it.
Without the template
Add the SDK to an existing Next.js app:
npm install @planeward/sdkClient component
The SDK handshakes with the Planeward host, then hands you a short-lived token. Send it to your own backend.
"use client";
import { useEffect, useState } from "react";
import { createPlanewardApp } from "@planeward/sdk";
export function Viewer() {
const [name, setName] = useState<string | null>(null);
useEffect(() => {
const app = createPlanewardApp();
(async () => {
await app.ready;
const token = await app.getToken();
const response = await fetch("/api/me", {
headers: { Authorization: `Bearer ${token}` },
});
const data: { name: string } = await response.json();
setName(data.name);
})();
return () => app.destroy();
}, []);
return <p>{name ? `Hello, ${name}` : "Loading…"}</p>;
}Route handler
Verify the token on your server. Never trust it without checking it was issued for your app.
import { verifyPlanewardToken } from "@planeward/sdk/server";
export async function GET(request: Request) {
const token = request.headers.get("authorization")?.replace("Bearer ", "");
if (!token) return Response.json({ error: "Missing token" }, { status: 401 });
try {
const claims = await verifyPlanewardToken(token, {
appId: process.env.PLANEWARD_APP_ID!,
});
return Response.json({ name: claims.name });
} catch {
return Response.json({ error: "Invalid token" }, { status: 401 });
}
}Set the URL on your app in Settings › Apps › Developer (http://localhost while you test in your own workspace, HTTPS once deployed), install it and add it as a channel. Next: Identity token, then Testing your app.
Planeward Docs