Skip to main content

​
Next.js SDK

The @instantschema/sdk package provides a <InstantSchemaHead> Server Component that fetches schemas and renders them into the HTML <head> before any JavaScript runs — giving you full SEO fidelity with no client-side requests.

​
Prerequisites

  • Next.js 14+ (App Router)
  • React 18+

​
Install

npm install @instantschema/sdk

​
Setup

​
1. Add the pathname middleware

Create middleware.ts at your project root. This exposes the current pathname to Server Components via a request header: 
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";

export function middleware(req: NextRequest) {
  const headers = new Headers(req.headers);
  headers.set("x-pathname", req.nextUrl.pathname);
  return NextResponse.next({ request: { headers } });
}

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

​
2. Add <InstantSchemaHead> to your root layout

// app/layout.tsx
import { InstantSchemaHead } from "@instantschema/sdk/next";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <head>
        <InstantSchemaHead projectId="YOUR_PROJECT_ID" />
      </head>
      <body>{children}</body>
    </html>
  );
}
Replace YOUR_PROJECT_ID with the Project ID from your InstantSchema dashboard.

​
How it works

<InstantSchemaHead> is an async Server Component. On each request it:
  1. Reads the x-pathname header set by the middleware
  2. Fetches schemas from the InstantSchema API for that pathname
  3. Renders them as <script type="application/ld+json" data-instantschema="1"> tags
The data-instantschema="1" attribute is how the dashboard detects the npm integration automatically on the next scan. No manual confirmation needed.

​
Detection

Once deployed, return to your dashboard. The integration panel will show Integration active · via Next.js SDK on the next scan of your site (usually within the next scheduled scan, or immediately if you trigger one manually).

​
API

​
InstantSchemaHead

import { InstantSchemaHead } from "@instantschema/sdk/next";

<InstantSchemaHead
  projectId="YOUR_PROJECT_ID"
  pathname="/optional-override"  // auto-read from middleware if omitted
  apiBase="https://app.instantschema.com"  // optional override
/>
PropTypeRequiredDescription
projectIdstringYesYour InstantSchema project ID
pathnamestringNoPage path; auto-read from x-pathname header if omitted
apiBasestringNoOverride API base URL

​
fetchSchemas

The lower-level function used by <InstantSchemaHead>. Use this if you need schemas outside the <head>: 
import { fetchSchemas } from "@instantschema/sdk";

const schemas = await fetchSchemas("YOUR_PROJECT_ID", "/blog/my-post");
Schemas are cached for 1 hour at the CDN layer (Cache-Control: s-maxage=3600).