> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instantschema.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Next.js SDK

> Server-render InstantSchema structured data in Next.js App Router

# 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

```bash theme={null}
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:

```ts theme={null}
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

```tsx theme={null}
// 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](https://app.instantschema.com).

## 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`

```tsx theme={null}
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>`:

```ts theme={null}
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`).
