Scaffold Starter App

The Hypercerts Scaffold is a working Next.js app that demonstrates how to build on ATProto with the Hypercerts SDK. It handles OAuth authentication, profile management, and the full hypercert creation workflow — from basic claims through evidence, locations, measurements, and evaluations.

Live at hypercerts-scaffold.vercel.app. Source: github.com/hypercerts-org/hypercerts-scaffold-atproto.

What the app does

Sign in with ATProto

Enter your handle (e.g. yourname.certified.app or yourname.bsky.social) and the app redirects you to your PDS for OAuth authorization. Once approved, you're signed in with a session tied to your DID.

Home screen

After signing in, the home screen shows your active session — your DID, display name, and handle. From here you can create a new hypercert or view your existing ones.

Create a hypercert

The creation flow is a 6-step wizard with a sidebar stepper that tracks your progress:

Step 1 — Basic info. Title, description, work scope tags, start and end dates, and an optional cover image. This creates the core org.hypercerts.claim.activity record on your PDS.

Step 2 — Evidence. Attach supporting documentation — URLs, files, or descriptions that back up the claim.

Step 3 — Location. Add geographic context to the work — where it happened.

Step 4 — Measurements. Add quantitative data — metrics, values, and measurement methods that make the impact concrete.

Step 5 — Evaluations. Add third-party assessments of the work.

Step 6 — Done. Review the completed hypercert and create another or view your collection.

Browse your hypercerts

The hypercerts page shows all your claims in a card grid. Each card displays the title, description, creation date, work scope tags, and cover image. Click any card to view its full details.

Edit your profile

The profile page lets you update your Certified profile — display name, bio, pronouns, website, avatar, and banner image. Changes are written directly to your PDS.

Screenshots needed: To add the screenshots above, capture each screen from hypercerts-scaffold.vercel.app and save them to documentation/public/images/scaffold/. Use the filenames referenced in each figure tag.

Run it locally

1. Clone and install:

git clone https://github.com/hypercerts-org/hypercerts-scaffold-atproto
cd hypercerts-scaffold-atproto
pnpm install

2. Configure environment:

cp .env.example .env.local
pnpm run generate-jwk >> .env.local

3. Start Redis (for session storage):

docker run -d -p 6379:6379 redis:alpine

4. Run the dev server:

pnpm run dev

Open http://127.0.0.1:3000. Requires Node.js 20+ and pnpm.

Use 127.0.0.1 not localhost for local development. ATProto OAuth requires IP-based loopback addresses per RFC 8252. The app auto-redirects, but your .env.local must use 127.0.0.1.

Environment variables

Key patterns

Getting an authenticated repository

import { getRepoContext } from "@/lib/repo-context";


export async function GET() {
  const ctx = await getRepoContext();
  if (!ctx) {
    return Response.json({ error: "Not authenticated" }, { status: 401 });
  }


  const profile = await ctx.scopedRepo.profile.getCertifiedProfile();
  return Response.json(profile);
}

The scopedRepo is routed to the authenticated user's PDS and scoped to their DID. Use it for all profile and hypercert operations.

Creating a hypercert

await ctx.scopedRepo.hypercert.create({
  title: "My Hypercert",
  description: "A certificate of impact",
  workScope: "Documentation",
  workTimeframeFrom: "2026-01-01",
  workTimeframeTo: "2026-03-31",
  rights: {
    name: "Public Display",
    type: "display",
    description: "Right to publicly display this contribution",
  },
});

Listing hypercerts

const hypercerts = await ctx.scopedRepo.hypercert.list();

Project structure

app/api/auth/     # OAuth endpoints
app/api/certs/    # Hypercert CRUD
app/api/profile/  # Profile management
components/       # React components
lib/              # SDK init, repo context, server actions
providers/        # React context providers
queries/          # TanStack Query hooks

Key files:

• lib/hypercerts-sdk.ts — SDK initialization
• lib/repo-context.ts — Helper to get authenticated repository
• lib/create-actions.ts — Server actions for common operations
• app/api/auth/callback/route.ts — OAuth callback handler

The scaffold uses a pre-release SDK version (@hypercerts-org/sdk-core@0.10.0-beta.8). API changes are expected before 1.0.