Quickstart

Before you start

Make sure you have:

• @nexa-ed/next and @nexa-ed/react installed — see Installation
• NEXA_API_KEY and NEXA_WEBHOOK_SECRET in your .env.local — both set to the same API key from the Nexa dashboard (Nexa signs webhooks with your API key)
• An auth provider (Clerk or NextAuth) set up in your app

What you'll have at the end: a working teacher dashboard with live OCR progress, structured student records, and a payment widget — wired to the Nexa API in two files.

Step 1 — Create the SDK instance

Create lib/nexa.ts. This is the one place you configure Nexa for your entire app.

import { createNexa } from "@nexa-ed/next";
import { auth } from "@clerk/nextjs/server"; // or your auth provider
 
export const nexa = createNexa({
  apiKey: process.env.NEXA_API_KEY!,
  webhookSecret: process.env.NEXA_WEBHOOK_SECRET!,
 
  // Resolve the current user from every incoming SDK request
  getUser: async () => {
    const { userId } = await auth();
    if (!userId) throw new Error("Unauthorized");
    return { userId };
  },
 
  // Called automatically when Nexa delivers a file.completed webhook
  onFileComplete: async ({ fileId, userId }) => {
    console.log(`File ${fileId} processed for user ${userId}`);
    // Save records to your database here
  },
 
  // Called automatically when a payment webhook arrives
  onPaymentComplete: async ({ reference, amount }) => {
    console.log(`Payment ${reference} confirmed — ₦${amount / 100}`);
  },
});

Step 2 — Mount the catch-all route

Create a single catch-all route. This one file handles every Nexa endpoint.

import { createRouteHandler } from "@nexa-ed/next";
import { nexa } from "@/lib/nexa";
 
export const { GET, POST } = createRouteHandler({ client: nexa });

That's the entire server-side setup. The route handler covers:

Step 3 — Wrap your app with NexaProvider

Add NexaProvider to your root layout so all React components and hooks can reach the SDK.

import { NexaProvider } from "@nexa-ed/react";
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <NexaProvider>
          {children}
        </NexaProvider>
      </body>
    </html>
  );
}

NexaProvider defaults basePath to /api/nexa — matching the route you just created. No props needed unless you mounted it at a different path.

Step 4 — Add your first component

Drop ResultsViewerSheet into any server or client page. It renders a full-featured slide-over with a pipeline timeline, student records grid, and stats panel — all wired automatically.

import { ResultsViewerSheet } from "@nexa-ed/react";
 
export default function TeacherDashboardPage() {
  return (
    <main>
      <h1>Teacher Dashboard</h1>
      <ResultsViewerSheet />
    </main>
  );
}

Configure webhook URLs

In the Nexa dashboard → Webhooks, register these URLs so Nexa can call back to your app:

Student email events (email.created, email.status_changed, email.bulk_completed) aren't handled by the catch-all route — see Webhooks → Email events if you provision student emails.

Use a tool like ngrok to expose localhost during development.

What's next

Now that the integration is live, explore what you can build:

• File Processing — submit PDFs, stream OCR progress, retrieve records
• Payments — initialize fees, verify transactions, handle webhooks
• Student Emails — provision student email accounts across all three tiers
• Domain Setup — verify your domain to unlock Tier 2/3 and your live key
• React Components — upload zone, records table, payment widget, email provisioning UI
• React Hooks — fine-grained control over every feature