When should I use this SDK (please read carefully)

• you should ONLY use this SDK if you are trying to register your RSCs (react server components) in Builder. That is its only advantage over our standard React SDKs.
• our Gen1 and Gen2 React SDKs also integrate with Next.js, but their supported Next.js versions must be checked separately in the framework version matrix. They do not support registration of RSCs.
• this SDK only works in the NextJS App Directory.

To allow registering RSCs, this SDK must make compromises. Most notably:

• it does not support interactive Builder features within the rendered content (such as updating dynamic bindings, state, actions etc.). As of today, there are no workarounds around these limitations, due to how RSCs work. See the features grid for more information.
• the visual editor experience is laggy, as it requires network roundtrips to the customer's servers for each edit. We are working on improving this.

this SDK is marked as "Beta" due to the missing features mentioned above. It is however actively maintained and developed alongside all other SDKs.

Builder.io React NextJS SDK (BETA)

This is the Builder NextJS SDK, @builder.io/sdk-react-nextjs. It is intended to be used only with NextJS's app directory, and has hard dependencies on NextJS-specific functionality that only works in the app directory.

Minimum supported version

The peerDependencies permit Next.js >=13.5.9 and React and React DOM >=18.2.0. These installation ranges apply only to this RSC-registration SDK; its E2E-tested minimum is Next.js 14.2.25 with React and React DOM 18.2.0 (Next.js 14 is no longer supported upstream); see the framework version matrix. Standard Gen1 and Gen2 React SDK integrations have separate Next.js support evidence.

Usage

When registering a custom component, you will need to add the isRSC: true option to the component. For example:

// CatFacts.tsx
async function CatFacts() {
  const catFacts = await fetch('https://cat-fact.herokuapp.com/facts').then(
    (x) => x.json()
  );
  return (
    <div>
      Here are some cat facts from an RSC:
      <ul>
        {catFacts.slice(3).map((fact) => (
          <li key={fact._id}>{fact.text}</li>
        ))}
      </ul>
    </div>
  );
}

export const CatFactsInfo = {
  name: 'CatFacts',
  component: CatFacts,
  // You must add the below option or the SDK will fail to render.
  isRSC: true,
};

And in your page.tsx, you can use the custom component like this:

// page.tsx
import {
  Content,
  fetchOneEntry,
  getBuilderSearchParams,
} from '@builder.io/sdk-react-nextjs';
import { CatFactsInfo } from './CatFacts';

export default async function Page(props) {
  const urlPath = '/' + (props.params?.slug?.join('/') || '');

  const content = await fetchOneEntry({
    model: 'page',
    apiKey,
    options: getBuilderSearchParams(props.searchParams),
    userAttributes: { urlPath },
  });

  return (
    <Content
      content={content}
      model="page"
      apiKey={apiKey}
      customComponents={[CatFactsInfo]}
    />
  );
}

For more usage information, look at the examples.

Mitosis

This SDK is generated by Mitosis. To see the Mitosis source-code, go here.

Feature Support

To check the status of the SDK, look at these tables.

Getting Started

npm install @builder.io/sdk-react-nextjs

Examples

• Next.js SDK