PlanewardPlaneward Docs
PlanewardPlaneward Docs
Welcome

Developers

REST APIAuthenticationWebhooksMCPEmbedded projectsTask description contentDeveloper hub
Community appsQuickstartIdentity tokenAPI accessApp webhooksTesting your apppostMessage protocol

API

Community apps

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/sdk

Client component

The SDK handshakes with the Planeward host, then hands you a short-lived token. Send it to your own backend.

app/viewer.tsx
"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.

app/api/me/route.ts
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.

Community apps

Build apps that run inside a Planeward community as an iframe.

Identity token

The signed JWT that tells your app who is viewing.

On this page

Start from the templateWithout the templateClient componentRoute handler