Builder.io React SDK v2

This is the React v2 SDK, @builder.io/sdk-react. It is a complete rewrite of the React SDK, and has the following benefits:

• zero client-side dependencies
• far smaller bundle size (25kb)

NOTE: if you are using the SDK in a webapp that gets deployed on a serverless environment (like Next or Hydrogen), you might need to import the SDK from @builder.io/sdk-react/edge. This is a special import that handles edge cases surrounding serverless environments.

Minimum supported version

The peerDependencies permit React >=16 (and React 19 release candidates). This is an installation range, not a guarantee of active support for React 16; see the framework version matrix.

API Reference

To use the SDK, you need to:

• fetch the builder data using fetchOneEntry: you can see how to use it here https://www.builder.io/c/docs/content-api, and how it differs from the React V1 SDK's builder.get() function.

• pass that data to the Content component. Here is a simplified example showing how you would use both:

import { Content, fetchOneEntry, isPreviewing } from '@builder.io/sdk-react';
import { useEffect, useState } from 'react';

const BUILDER_PUBLIC_API_KEY = 'YOUR API KEY';

function App() {
  const [content, setContent] = useState(undefined);

  useEffect(() => {
    fetchOneEntry({
      model: 'page',
      apiKey: BUILDER_PUBLIC_API_KEY,
      userAttributes: {
        urlPath: window.location.pathname || '/',
      },
    }).then((content) => {
      setContent(content);
    });
  }, []);

  const shouldRenderBuilderContent = content || isPreviewing();

  return shouldRenderBuilderContent ? (
    <Content content={content} model="page" apiKey={BUILDER_PUBLIC_API_KEY} />
  ) : (
    <div>Content Not Found</div>
  );
}

Look at the examples for more information.

Multiple Content components on one page

Each Content that contains a Variant Container or an A/B test inlines a copy of the helper scripts those features need. If a page renders several Content components (for example a header, the page body and a footer), wrap them once in BuilderScripts so the helpers are emitted a single time:

import { BuilderScripts, Content } from '@builder.io/sdk-react';

export default function Layout({ children }) {
  return <BuilderScripts nonce={cspNonce}>{children}</BuilderScripts>;
}

Use one BuilderScripts above every Content that uses these features, not one around each Content. Sibling wrappers each emit their own copy. A BuilderScripts nested inside another one emits nothing, so adding an extra one lower in the tree is safe. The nonce prop is optional and only needed with a Content Security Policy. BuilderScripts always emits the helpers, even if nothing inside it uses personalization or A/B tests, so place it only around pages that do.

Next.js App Router

Don't import BuilderScripts from @builder.io/sdk-react directly in a server component such as app/layout.tsx. Next.js then loads a different build of the SDK for it in the browser than the one your "use client" component uses for Content, so Content can't see the wrapper. The server HTML has one helper script, the browser renders one per Content, and hydration fails.

Re-export it from a client file and import that instead:

// components/builder-scripts.tsx
'use client';
export { BuilderScripts } from '@builder.io/sdk-react';

// app/layout.tsx
import { BuilderScripts } from '../components/builder-scripts';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <BuilderScripts>{children}</BuilderScripts>
      </body>
    </html>
  );
}

Wrapping the Content components inside the same client component also works.

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

Examples

• React + Vite
• Next.js App Router
• Next.js Pages Router

Fetch

This Package uses fetch. See these docs for more information.