Using HelloJohn with Next.js Edge Runtime — Vercel Edge Functions, Cloudflare Workers, and local JWT verification without network calls.

Edge Runtime

HelloJohn's Next.js SDK is fully compatible with the Edge Runtime. JWT verification happens locally using the JWKS public key — no round-trip to HelloJohn's API required.

How Edge Auth Works

In Edge environments (Vercel Edge Functions, Cloudflare Workers, Next.js Edge middleware), @hellojohn/nextjs verifies JWTs locally:

On first request: fetches and caches the JWKS public key from /.well-known/jwks.json
On subsequent requests: verifies the JWT signature using the cached public key
No network call to HelloJohn per request

This means edge authentication is:

Fast: sub-millisecond token verification
Offline-capable: works without reaching HelloJohn on every request
Globally distributed: runs at the edge, close to the user

Middleware (Edge by Default)

Next.js middleware runs at the edge automatically. HelloJohn's middleware is edge-compatible:

// middleware.ts — runs in Edge Runtime
import { hellojohnMiddleware } from "@hellojohn/nextjs";

export default hellojohnMiddleware({
  publicRoutes: ["/", "/sign-in"],
});

export const config = {
  matcher: ["/((?!_next|.*\\..*).*)"],
};

Edge Route Handlers

To run a Route Handler at the edge:

// app/api/edge-auth/route.ts
import { auth } from "@hellojohn/nextjs/server";
import { NextResponse } from "next/server";

export const runtime = "edge"; // Run in Edge Runtime

export async function GET() {
  const { userId } = await auth();

  if (!userId) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  return NextResponse.json({ userId });
}

Cloudflare Workers

For Cloudflare Workers using @hellojohn/js (framework-agnostic):

import { HelloJohn } from "@hellojohn/js";

const hj = new HelloJohn({
  tenantId: HELLOJOHN_TENANT_ID,
  publicKey: HELLOJOHN_PUBLIC_KEY, // Ed25519 public key for local verification
});

export default {
  async fetch(request: Request): Promise<Response> {
    const token = request.headers.get("Authorization")?.split(" ")[1];

    if (!token) {
      return new Response("Unauthorized", { status: 401 });
    }

    const { payload, error } = await hj.verifyToken(token);

    if (error) {
      return new Response("Invalid token", { status: 401 });
    }

    return new Response(`Hello, ${payload.sub}`);
  },
};

HelloJohn caches the JWKS for 24 hours by default. During a key rotation, both the old and new public keys are present in the JWKS endpoint simultaneously to prevent verification failures during the rotation window.

To configure cache duration (edge environments):

import { hellojohnMiddleware } from "@hellojohn/nextjs";

export default hellojohnMiddleware({
  jwksCacheDuration: 3600, // Cache JWKS for 1 hour (default: 86400)
});

Limitations

Feature	Edge Support
JWT verification	✅ Full support
`auth()` helper	✅ Full support
`currentUser()`	⚠️ Makes a network request — use sparingly in edge
Node.js SDK	❌ Node.js only — use `@hellojohn/js` instead
Database access (Prisma/Drizzle)	❌ Not supported in Edge

For full currentUser() data in edge routes, use edge-compatible data stores (KV, D1, Durable Objects) and sync user data from HelloJohn via webhooks.

Edge Runtime

Edge Runtime

How Edge Auth Works

Middleware (Edge by Default)

Edge Route Handlers

Cloudflare Workers

JWKS Caching

Limitations

On this page