Guide · Open source

How to use Puck: install, configure and render a visual React editor

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Puck is an open-source visual editor for React that lets people build pages by dragging and arranging components you define. This guide shows developers how to install it, describe components in a config, render the editor and display the saved page. By the end you will have a working editor and a page that renders the data it produces.

Puckpuckeditor/puck · ★ 13.6k · MIT Install options & downloads

Quick start

1Check prerequisites. Make sure Node.js and npm are installed, since the README lists them as requirements.
2Install the package. Run npm i @puckeditor/core --save in your project, or use npx create-puck-app my-app to start from a recipe.
3Define a config. Create a config object with a components entry for each block editors may use, including its fields and render function.
4Render the editor. Use the Puck component with your config, initial data and an onPublish callback that saves to your storage.
5Render the page. Use the Render component with the config and saved data to display the page to visitors.
6Pick a recipe if needed. Explore the next or react-router recipes if you want a working Next.js or React Router setup.

What Puck is and who it is for

Puck is a modular, open-source visual editor for React.js. You use it to build custom drag-and-drop experiences with your own application and React components.

Because Puck is just a React component, it works in React environments including Next.js. The README says you own your data and there is no vendor lock-in. Puck is MIT licensed, so it can be used in internal systems and commercial applications.

Good fit: React developers adding a page builder to an existing app
Good fit: teams where content editors arrange pre-approved components
Not a fit: people who want a hosted website builder with no coding, since Puck is a library you integrate

Install the Puck package with npm

You need Node.js and npm. Install the core package into your project with the command below, or create a pre-configured app with create-puck-app.

npm i @puckeditor/core --save # or npx create-puck-app my-app

Define your components in a Puck config

Puck works from a config object. Each entry under components describes a component: its fields, which control what editors can change, and a render function that outputs the React markup. The example config defines a HeadingBlock with a text field named children that renders an h1.

The config is the set of components you approve. Editors can only arrange what you define here.

fields: describes the inputs editors can set (the example uses type text)
render: a function that receives the field values and returns JSX

const config = {
  components: {
    HeadingBlock: {
      fields: {
        children: {
          type: "text",
        },
      },
      render: ({ children }) => {
        return <h1>{children}</h1>;
      },
    },
  },
};

Render the Puck editor and save data

The Puck component takes a config, the initial data and an onPublish callback. The example starts with empty initial data and a save function that receives the data when the page is published. In a real app, that function would write the data to your database.

The README's example stores data in a placeholder save function, so you must add your own storage logic.

config: the component definitions from the previous step
data: the initial page data (the example uses an empty object)
onPublish: called with the data to save it

import { Puck } from "@puckeditor/core";

const save = (data) => {};

export function Editor() {
  return <Puck config={config} data={initialData} onPublish={save} />;
}

Render the saved page for visitors

To display a page, use the Render component with the same config and the saved data. The README shows this as a separate page file, so visitors see the output without the editor interface.

import { Render } from "@puckeditor/core";

export function Page() {
  return <Render config={config} data={data} />;
}

Start from a recipe to skip setup

The create-puck-app command can spin up a pre-configured app from the project's recipes. The README lists two: next, which uses Next.js App Router and static page generation, and react-router, a React Router v7 example that uses dynamic routes to create pages at any level.

next: Next.js example using App Router and static page generation
react-router: React Router v7 example using dynamic routes

npx create-puck-app my-app

Where to get help and extensions

For questions, the README points to GitHub issues and the Discord server. The awesome-puck community repo collects plugins, custom fields and more. For hands-on support and consultancy, the README links to a discovery call booking page.

GitHub issues: https://github.com/puckeditor/puck/issues
Discord: https://discord.gg/D9e4E3MQVZ
awesome-puck: community plugins and custom fields

What people use it for

Adding a page builder to an existing React or Next.js app so staff can create landing pages
Letting content editors arrange pre-approved components such as headings and sections
Creating pages at any level with dynamic routes in a React Router app, using the react-router recipe
Building an internal or commercial tool with an MIT-licensed, self-hosted editor

Frequently asked questions

Is Puck free to use?

Puck is released under the MIT license, which the README says makes it suitable for both internal systems and commercial applications. Check the repository's license file for the full terms.

What do I need to install Puck?

The README lists Node.js and npm as prerequisites. You install the package with npm i @puckeditor/core --save.

Does Puck work with Next.js?

Yes. The README says Puck is a React component that works in React environments including Next.js, and it includes a next recipe using App Router and static page generation.

Is Puck a website builder with hosting?

No. The README describes Puck as a library you integrate into your own code. It does not mention hosting, so it is not a ready-made website builder for people who do not code.

How do I get help if something breaks?

The README says to open a GitHub issue or join the Discord server. It also links to a discovery call for hands-on support and consultancy.

How does Puck compare to GrapesJS, Builder.io or Craft.js?

The source lists GrapesJS, Builder.io and Craft.js as comparable projects but does not compare features. Evaluate them against your needs, such as React support and licensing.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Puck suits React developers who want to add a visual page editor to their own app, with components they control and data they own under an MIT license. If you want a ready-made website builder with hosting and no coding, or you work outside React, pick a different tool.

Install options & downloads