Skip to content
Skip to main contentWhere does your team stand on AI adoption?
CONTACT SALESSTART BUILDING

Devtools manual React setup

Prerequisites

  • Node.js
  • A React project created with Create React App or another React framework
  • A Builder account with an API key

Set up

1. Install the required packages

Run the following command to install the necessary packages for Builder and React:

npm install --save-dev concurrently @builder.io/dev-tools @builder.io/react

2. Add a dev task to npm scripts

Update the scripts section in your package.json file to include a development task. This task runs both the React development server and Builder Dev Tools concurrently:

//package.json "scripts": { // ...existing code... "dev": "concurrently \"react-scripts start\" \"builder-dev-tools\"" }

Make sure you have concurrently installed. If not, install it using:

npm install concurrently --save-dev

3. Create a .env file with your Builder API key

Add your Builder API key to a .env file in the root of your project:

REACT_APP_PUBLIC_BUILDER_KEY=<YOUR_BUILDER_API_KEY>

Press Cmd/Ctrl + k and filter for api to get your Public API Key. For details see Using Builder API Keys.

4. Create a builder-registry.ts file

Create a new file at src/builder-registry.ts to register your custom components with Builder.

This file defines the components that will be available in the Visual Editor.

touch ./src/builder-registry.ts

In src/builder-registry.ts, define and register any custom components you want to use within Builder.

Starter template:

// builder.registry.ts import { Builder } from "@builder.io/react"; // Import your custom components // import { YourCustomComponent } from './components/YourCustomComponent'; // Register your custom components // Builder.registerComponent(YourCustomComponent, { // name: 'Your Custom Component', // inputs: [ // { name: 'text', type: 'string' } // ] // }); // Initialize Builder with your API key Builder.init(process.env.REACT_APP_PUBLIC_BUILDER_KEY);

For more details on registering components, see Register custom components.

5. Create a Figma imports component

Create a new component at src/components/figma-imports.tsx to preview Figma imports within Builder.

import React from "react"; import { BuilderComponent, builder, useIsPreviewing } from "@builder.io/react"; // Builder Public API Key set in .env file builder.init(process.env.REACT_APP_PUBLIC_BUILDER_KEY!); export default function BuilderPage() { const isPreviewingInBuilder = useIsPreviewing(); const [notFound, setNotFound] = useState(false); const [content, setContent] = useState(null); // get the page content from Builder useEffect(() => { async function fetchContent() { const content = await builder .get("figma-imports", { url: window.location.pathname, }) .promise(); setContent(content); setNotFound(!content); // if the page title is found, // set the document title if (content?.data.title) { document.title = content.data.title; } } fetchContent(); }, []); if (content === null) { return null; } // If no page is found, return // a 404 page from your code. if (notFound && !isPreviewingInBuilder) { return <div>404 Page Not Found</div>; } // return the page when found return ( <> {/* Render the Builder page */} <BuilderComponent model="figma-imports" content={content} /> </> ); }

You can do the following with the Figma imports component:

  • Preview designs imported from Figma within your React application
  • See how your custom components render with Builder.io content
  • Test the integration between Builder.io and your React app

6. Add the Figma imports component to your router

Add the figma-imports component as a route in your React router only in development mode.

For example, you can conditionally render the route based on the environment:

import { createBrowserRouter } from "react-router-dom"; import Root from "./components/Root"; import FigmaPlugin from "./components/figma-imports"; const routes = [ { path: "/", element: <Root />, }, // ...existing routes... ]; // Only add the Figma plugin route in development if (process.env.NODE_ENV === "development") { import("./builder-registry"); routes.push({ path: "/figma-imports", element: <FigmaPlugin />, }); } const router = createBrowserRouter(routes); export default router;

Test your set up

After completing the setup, follow these steps to verify that everything is working correctly:

  1. Start your developement server using npm run dev.
  2. Navigate to http://localhost:3000/figma-imports in your browser.
  3. If everything is set up correctly, you should see either a blank page or existing content from Builder for the figma-imports model.
  4. You can configure your components in Visual Editor and they will appear in your React application.

Troubleshoot your app

  • Blank page: verify that the API key is correct and that content exists for the figma-imports model in Builder.
  • 404 error: check if the route is correctly configured in the router.
  • Component not rendering: verify that components are registered in builder-registry.ts.
  • Build errors: confirm that all dependencies are installed and that the React version is compatible with Builder.

What's next

Now that you have set up Devtools for React, you can do the following with Builder:

  • Register custom components in the builder-registry.ts file.
  • Create content in Builder using the Visual Editor.
  • Import designs from Figma and map them to your components.
  • Configure content models in Builder.
  • Integrate Builder content into your main app.

For more details, see the Builder React documentation.

Was this article helpful?