Recommended Setup for 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 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.

To start, we create a unified ClientWrapper (code), 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 sets the last seen timestamp in Schematic.

1
const { identify } = useSchematicEvents();
2
const authContext = useAuthContext();
3
4
useEffect(() => {
5
  const { company, user } = authContext ?? {};
6
  if (company && user) {
7
    setTimeout(() => {
8
      identify({
9
        company: {
10
          keys: company.keys,
11
          name: company.name,
12
        },
13
        keys: user.keys,
14
        name: user.name,
15
      });
16
    }, 0)
17
  }
18
}, [authContext, identify]);

In this example, useAuthContext (code) is responsible for providing user and company info from your auth provider in a structured format.

Schematic Components

Schematic components 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. 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.

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). A reproduction of our hook can be found here.

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.