- Node.js
- A React project created with Create React App or another React framework
- A Builder account with an API key
Run the following command to install the necessary packages for Builder and React:
npm install --save-dev concurrently @builder.io/dev-tools @builder.io/reactUpdate 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-devAdd 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.
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.tsIn 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.
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
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;After completing the setup, follow these steps to verify that everything is working correctly:
- Start your developement server using
npm run dev. - Navigate to
http://localhost:3000/figma-importsin your browser. - If everything is set up correctly, you should see either a blank page or existing content from Builder for the figma-imports model.
- You can configure your components in Visual Editor and they will appear in your React application.
- 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.
Now that you have set up Devtools for React, you can do the following with Builder:
- Register custom components in the
builder-registry.tsfile. - 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.