> If you are setting up, configuring, or answering questions about Schematic, connect the
> Schematic MCP server before working from these pages. It reads and writes plans, features,
> entitlements, and overrides against the real account, so what you report and what you build
> match what actually exists.
>
> The server is at https://api.schematichq.com/mcp
>
> From Claude, ChatGPT, or another chat assistant, add it as a custom connector:
> https://docs.schematichq.com/working-with-ai
>
> From a coding assistant such as Claude Code, Codex, or Cursor:
> https://docs.schematichq.com/building-with-ai
>
> For clean Markdown of any page, append `.md` to the page URL. For a complete page index,
> see https://docs.schematichq.com/llms.txt

# Recommended Setup for Next.js

> Our recommended setup for using the Schematic React SDK with Next.js.

This guide provides recommendations for setting up Schematic in your Next.js application. This guide is intended as an extension of our React SDK guide, with specific recommendations and approaches tailored for Next.js. If you haven't already, we recommend reading our [React SDK guide](/developer_resources/sdks/react) first.

These recommendations are based on our experiences working with Next.js, as well as our customers who use Next.js.

## Overview

This section includes suggestions on the following topics:

* Installing `SchematicProvider` and using `identify` to set the user context
* Leveraging Schematic components and temporary access tokens

## SchematicProvider

The `SchematicProvider` is a Provider that enables Schematic hooks and components. It provides the user/company context for all flag checks and event tracking. We recommend combining this wrapper with your auth provider, since it will depend on the data provided by your auth provider.

In these examples, we'll use Clerk, but this should work for any auth provider. We setup clerk as directed [here](https://clerk.com/docs/nextjs/getting-started/quickstart).

To start, we create a unified `ClientWrapper` ([code](https://github.com/SchematicHQ/schematic-next-example/blob/main/src/components/ClientWrapper.tsx)), that combines the Clerk provider, Schematic provider, and additionally ensures we are operating on the client side (a requirement for the Schematic React SDK).

The most important part is calling `identify`, which sets the user/company context for flag checks and updates the last seen timestamp in Schematic.

```tsx
const { identify } = useSchematicEvents();
const authContext = useAuthContext();

useEffect(() => {
  const { company, user } = authContext ?? {};
  if (company && user) {
    setTimeout(() => {
      identify({
        company: {
          keys: company.keys,
          name: company.name,
        },
        keys: user.keys,
        name: user.name,
      });
    }, 0)
  }
}, [authContext, identify]);
```

In this example, `useAuthContext` ([code](https://github.com/SchematicHQ/schematic-next-example/blob/main/src/hooks/useAuthContext.ts)) is responsible for providing user and company info from your auth provider in a structured format.

## Schematic Components

[Schematic components](/components/overview) are React components that can be embedded in your application to provide a complete plan management UI to end users. They are pre-built and customizable, and can be embedded in your application using a Component ID from Schematic.

To embed a component, you'll need to generate an access token for the company. In Next.js this is easy to setup using the `/api` folder as shown [here](https://github.com/SchematicHQ/schematic-next-example/blob/main/src/app/api/accessToken/route.ts). This code reuses some of our authorization code to pull the correct company information.

For the component itself, we typically see users creating a dedicated page for it. A sample page, with appropriate error handling and loading states, is shown [here](https://github.com/SchematicHQ/schematic-next-example/blob/main/src/app/usage/page.tsx).

*Note: Components must be loaded client side (`"use client"`), and will error during server-side rendering if not.*

## Unified Entitlement and Permission Hook

"Can a user do XXX" typically requires two checks: entitlements and permissions. To keep our code base cleaner, the Schematic web app uses a unified entitlement and permission hook that combines the `useSchematicEntitlement` and permission checks (using Clerk permission).

This hook provides a few values derived out of the permission and entitlements that are commonly needed:

* `canView`: Is the user allowed to view these items **AND** is this feature enabled?
* `canEdit`: Can the user edit these items (assumes `canView` is true)
* `canCreate`: Can the user create these items **AND** is there quota left to do so?
* `featureUsage` and `featureAllocation`: These are surfaced from `useSchematicEntitlement` as they are commonly needed in the UI.

Together these cover the common permission and entitlement checks needed in the UI. If you use a separate feature flagging system, you can easily incorporate it into this hook as well.