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:

Reads the x-pathname header set by the middleware
Fetches schemas from the InstantSchema API for that pathname
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
/>

Prop	Type	Required	Description
`projectId`	`string`	Yes	Your InstantSchema project ID
`pathname`	`string`	No	Page path; auto-read from `x-pathname` header if omitted
`apiBase`	`string`	No	Override 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).

Getting Started

Integrations

API Reference

Troubleshooting

Next.js SDK

Next.js SDK

Prerequisites

Install

Setup

1. Add the pathname middleware

2. Add `<InstantSchemaHead>` to your root layout

How it works

Detection

API

`InstantSchemaHead`

`fetchSchemas`

​Next.js SDK

​Prerequisites

​Install

​Setup

​1. Add the pathname middleware

​2. Add <InstantSchemaHead> to your root layout

​How it works

​Detection

​API

​InstantSchemaHead

​fetchSchemas

Next.js SDK

Prerequisites

Install

Setup

1. Add the pathname middleware

2. Add `<InstantSchemaHead>` to your root layout

How it works

Detection

API

`InstantSchemaHead`

`fetchSchemas`