Getting Started with Puck AI

Prerequisites

• Familiarity with Puck Editor
• Puck 0.21 or greater
• A Puck Cloud account, with sufficient credit
• Recommended: A fresh create-puck-app application to get familiar with the API.

Setup the AI plugin

The easiest way to start using Puck AI is via the AI plugin with a chat interface.

Install package

Install the @puckeditor/plugin-ai package:

npm i @puckeditor/plugin-ai --save

pnpm add @puckeditor/plugin-ai

yarn add @puckeditor/plugin-ai

bun add @puckeditor/plugin-ai

Load the plugin

Load the plugin:

import { createAiPlugin } from "@puckeditor/plugin-ai";
import "@puckeditor/plugin-ai/styles.css";
 
const aiPlugin = createAiPlugin();
 
export function Editor() {
  return (
    <Puck
      plugins={[aiPlugin]}
      // ...
    />
  );
}

Your Puck editor should now show the “AI” plugin in the plugin bar on the left. Click it to present the chat interface.

Configure the backend

Before you can prompt the agent, you need to configure your backend to proxy requests made by the plugin to the Puck Cloud.

Install cloud client

Install the @puckeditor/cloud-client package:

npm i @puckeditor/cloud-client --save

pnpm add @puckeditor/cloud-client

yarn add @puckeditor/cloud-client

bun add @puckeditor/cloud-client

Generate an API key

Generate an API key via the dashboard and set it under the PUCK_API_KEY environment variable. If you’re using dotenv:

PUCK_API_KEY=SECRET

Add server-side endpoints

Mount the Puck handler server-side to create endpoints for /api/puck/* using the puckHandler() API. This will enable the plugin to speak to the Puck Cloud.

// app/api/puck/[...all]/route.ts

import { puckHandler } from "@puckeditor/cloud-client";

export const POST = (request) => {
  return puckHandler(request, {
    ai: {
      context: "We are Google. You create Google landing pages.",
    },
  });
};

Enter a prompt

You can now return to the Puck instance and enter a prompt. Here are some suggestions:

• Hi. What can you do?
• Create a page about dogs
• Remove the heading block from the page

Puck AI will respond to your messages, and generate pages based on the available components in your Puck config.