Puck AIHeadless Generation

Headless Generation

Headless generation allows you to generate Puck pages programmatically.

Generate a page

Use the generate() API tool to generate Puck Data based on a natural-language prompt and Puck config.

import { generate } from "@puckeditor/cloud-client";
 
const page = await generate({
  prompt: "Create a page about dogs",
  config: {
    components: {
      HeadingBlock: {
        fields: {
          title: { type: "text" },
        },
        render: ({ title }) => title,
      },
    },
  },
});
// { root: { props: { title: "Pawesome Friends" } }, content: [ { type: "HeadingBlock", props: { id: "Heading-12345", title: "Discover Man's Best Friend" } } ] }

The output data can be provided to <Puck> for human-modification, or rendered directly with <Render>.

Execution time will vary based on the complexity of your prompt.

Update an existing page

You can use generate() to update existing data by providing it to the pageData parameter.

import { generate } from "@puckeditor/cloud-client";
 
const page = await generate({
  prompt: "Replace all mentions of Dog with Cat",
  config: {
    components: {
      HeadingBlock: {
        fields: {
          title: { type: "text" },
        },
        render: ({ title }) => title,
      },
    },
  },
  pageData: {
    root: { props: { title: "Dogs: Man's Best Friend" } },
    content: [],
  },
});
// { root: { props: { title: "Cats: Man's Best Friend" } }, content: [] }

Generate with design mode

Set mode to "design" to let the agent create new component types, as described in design mode.

import { generate } from "@puckeditor/cloud-client";
 
const page = await generate({
  prompt: "Create a pricing section with three tiers",
  config: { components: {} }, // Design mode doesn't require any components
  mode: "design",
});

Customizing design behavior

Pass designMode to tune how the agent designs:

const page = await generate({
  // ...
  mode: "design",
  designMode: {
    instructions: "Use our brand colors: #4285F4 for primary.",
    scripts: true, // Allow client-side scripts. Disabled by default
    model: "openai/gpt-5.6-sol", // Defaults to openai/gpt-5.6-luna
    providerOptions: {
      openai: { reasoningEffort: "high" },
    },
  },
});

Rendering the result

Designed components are returned on the data’s root under _dynamicConfig, so the config you render with must be passed through withDynamicConfig:

import { withDynamicConfig } from "@puckeditor/plugin-ai";
 
const page = await generate({ mode: "design" /* ... */ });
 
// Registers the designed components and page-wide styles/script
return <Render config={withDynamicConfig(config, page)} data={page} />;

Store the returned data verbatim. Dropping _dynamicConfig from the root props will strip the designed components from the page.