create-puck-app 0.22.2 → 0.22.3

package/index.js

@@ -66,11 +66,18 @@ program
     Explicitly tell the CLI to bootstrap the application using Yarn
   `
   )
+  .option(
+    "--ai",
+    `
+
+    Add Puck AI to the editor (requires a Puck Cloud account)
+  `
+  )
   .action(async (_appName, options) => {
-    const beforeQuestions = [];
+    const questions = [];
 
     if (!_appName) {
-      beforeQuestions.push({
+      questions.push({
         type: "input",
         name: "appName",
         message: "What is the name of your app?",
@@ -78,26 +85,27 @@ program
       });
     }
 
-    const questions = [
-      ...beforeQuestions,
-      {
-        type: "list",
-        name: "recipe",
-        message: "Which recipe would you like to use?",
-        required: true,
-        default: "next",
-        choices: [
-          {
-            name: "Next.js",
-            value: "next",
-          },
-          {
-            name: "React Router",
-            value: "react-router",
-          },
-        ],
-      },
-      {
+    questions.push({
+      type: "list",
+      name: "recipe",
+      message: "Which recipe would you like to use?",
+      required: true,
+      default: "next",
+      choices: [
+        {
+          name: "Next.js",
+          value: "next",
+        },
+        {
+          name: "React Router",
+          value: "react-router",
+        },
+      ],
+    });
+
+    // If the user didn't specify the --ai flag, ask them if they want to add Puck AI to the editor.
+    if (!options.ai) {
+      questions.push({
         type: "confirm",
         name: "puckAi",
         message: `Puck AI (beta) lets you generate pages using your own components. Learn more: ${ansiColors.cyan}https://puckeditor.com/docs/ai/overview${ansiColors.reset}
@@ -105,8 +113,8 @@ program
   Add Puck AI to the editor? (Requires a Puck Cloud account)`,
         required: true,
         default: true,
-      },
-    ];
+      });
+    }
 
     const answers = await inquirer.prompt(questions);
 
@@ -120,7 +128,7 @@ program
     }
 
     const recipe = answers.recipe;
-    const usesPuckAi = answers.puckAi;
+    const usesPuckAi = answers.puckAi || !!options.ai;
 
     // Copy template files to the new directory
     const recipeName = `${recipe}${usesPuckAi ? "-ai" : ""}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-puck-app",
-  "version": "0.22.2",
+  "version": "0.22.3",
   "author": "Chris Villa <chris@puckeditor.com>",
   "repository": "puckeditor/puck",
   "bugs": "https://github.com/puckeditor/puck/issues",

package/templates/next/README.md

@@ -1,38 +1,112 @@
-# `next` recipe
+# Puck + Next.js recipe
 
-The `next` recipe showcases one of the most powerful ways to implement Puck using to provide an authoring tool for any route in your Next app.
+[Puck](https://puckeditor.com) is the open-source visual editor for React.
 
-## Demonstrates
+This recipe connects Puck to the [Next.js App Router](https://nextjs.org/docs/app), so you can create and edit pages for any route in this app.
 
-- Next.js App Router implementation
-- JSON database implementation with HTTP API
-- Catch-all routes to use puck for any route on the platform
-- Incremental static regeneration (ISR) for all Puck pages
+## Core concepts
 
-## Usage
+If you're new to Puck, this section introduces the core concepts you need to know.
 
-Run the generator and enter `next` when prompted
+### Puck
 
+The Puck visual editor has three main parts: a config, the editor, and the renderer.
+
+#### Config
+
+The [config](https://puckeditor.com/docs/integrating-puck/component-configuration) registers the components users can use to build pages in the editor and the fields they can edit.
+
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      fields: {
+        title: { type: "text" },
+      },
+      render: ({ title }) => <h1>{title}</h1>,
+    },
+  },
+};
 ```
-npx create-puck-app my-app
+
+#### The editor
+
+The [`<Puck>`](https://puckeditor.com/docs/api-reference/components/puck) component renders the editor. It uses a config, exports [pages as JSON](https://puckeditor.com/docs/api-reference/data-model/data), and accepts initial page data for editing existing pages.
+
+```tsx
+<Puck
+  config={config} // The components available to the editor
+  data={data} // The page JSON to edit
+  onPublish={(data) => {
+    // Save data to your database
+  }}
+/>
 ```
 
-Start the server
+#### The renderer
 
+The [`<Render>`](https://puckeditor.com/docs/api-reference/components/render) component renders pages. It expects the page JSON and the config used to create that page.
+
+```tsx
+<Render
+  config={config} // The components used to create the page
+  data={data} // The page JSON to render
+/>
 ```
-yarn dev
+
+## Run the recipe
+
+### 1. Start the development server
+
+Run:
+
+```sh
+npm run dev
 ```
 
-Navigate to the homepage at https://localhost:3000. To edit the homepage, access the Puck editor at https://localhost:3000/edit.
+Once the server is running, navigate to [http://localhost:3000](http://localhost:3000) to view the home page, or [http://localhost:3000/edit](http://localhost:3000/edit) to edit it with Puck.
+
+### 2. Create a page
+
+Navigate to [http://localhost:3000/edit](http://localhost:3000/edit), open the `Blocks` tab in the left sidebar and build your page by dragging components onto the canvas.
+
+### 3. Publish the page
+
+Once your page is ready, select **Publish** in the header to save the result, then navigate to [http://localhost:3000](http://localhost:3000) to view the published page.
+
+You can also create a page at any path by navigating to `/your/path/edit` and publishing it. The route `/your/path` will render the page.
+
+## How it works
+
+When a URL ends in `/edit`, [`proxy.ts`](https://nextjs.org/docs/app/api-reference/file-conventions/proxy) sends the request to the Puck editor route (`app/puck/[...puckPath]/page.tsx`). The editor loads the saved page, or starts with an empty page if the path is new.
+
+Selecting **Publish** sends the page data to the `/puck/api` endpoint (`app/puck/api/route.ts`). The handler writes the JSON to `database.json` and clears the Next.js cache for that page. The catch-all route (`app/[...puckPath]/page.tsx`) then loads the same data and renders it with [`<Render>`](https://puckeditor.com/docs/api-reference/components/render).
+
+The table below shows the files that implement this flow.
+
+| File                                | Purpose                                                                                            |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `puck.config.tsx`                   | Defines the components, fields, and default props available to Puck. Add your own components here. |
+| `app/puck/[...puckPath]/page.tsx`   | Loads page data for the editor.                                                                    |
+| `app/puck/[...puckPath]/client.tsx` | Renders the editor and publishes changes.                                                          |
+| `app/[...puckPath]/page.tsx`        | Loads and renders published pages.                                                                 |
+| `app/puck/api/route.ts`             | Saves published pages.                                                                             |
+| `proxy.ts`                          | Routes URLs ending in `/edit` to `/puck/[...puckPath]/page.tsx`.                                   |
+| `lib/get-page.ts`                   | Reads page data from `database.json`. Replace this with your own data fetching logic.              |
+| `database.json`                     | Acts as a local database. Replace this with your own database solution.                            |
 
-You can do this for any route on the application, **even if the page doesn't exist**. For example, visit https://localhost:3000/hello/world and you'll receive a 404. You can author and publish a page by visiting https://localhost:3000/hello/world/edit. After publishing, go back to the original URL to see your page.
+## Before deploying to production
 
-## Using this recipe
+Before deploying this recipe, make sure to:
 
-To adopt this recipe you will need to:
+- **Protect the editor and API.** The `/edit` routes and `/puck/api` endpoint are public by default. Add authentication and authorization so only trusted users can edit or publish pages.
+- **Add your component library.** Replace the example `HeadingBlock` in `puck.config.tsx` with the components and fields your users need.
+- **Use a real database.** Replace `database.json` in `lib/get-page.ts` and `app/puck/api/route.ts`. Local files are not reliable across server instances or serverless deployments.
+- **Choose a rendering strategy.** `app/[...puckPath]/page.tsx` uses `force-static`. Remove it if a page needs request-time data such as headers, cookies, or user sessions.
 
-- **IMPORTANT** Add authentication to `/edit` routes. This can be done by modifying the example API routes in `/app/puck/api/route.ts` and server component in `/app/puck/[...puckPath]/page.tsx`. **If you don't do this, Puck will be completely public.**
-- Integrate your database into the API calls in `/app/puck/api/route.ts`
-- Implement a custom puck configuration in `puck.config.tsx`
+## Learn more
 
-By default, this recipe will generate static pages by setting `dynamic` to [`force-static`](https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config#dynamic) in the `/app/[...puckPath]/page.tsx`. This will strip headers and cookies. If you need dynamic pages, you can delete this.
+- [Puck documentation](https://puckeditor.com/docs)
+- [Getting started with Puck](https://puckeditor.com/docs/getting-started)
+- [Integrating Puck](https://puckeditor.com/docs/integrating-puck/component-configuration)
+- [Puck Discord](https://discord.gg/D9e4E3MQVZ)

package/templates/next-ai/README.md

@@ -1,60 +1,169 @@
-# `next-ai` recipe
+# Puck AI + Next.js recipe
 
-The `next-ai` recipe showcases one of the most powerful ways to combine Puck and [Puck AI](https://puckeditor.com/docs/ai/overview): providing an authoring tool with AI page generation capabilities for any route in your Next app.
+[Puck](https://puckeditor.com) is the open-source visual editor for React. It lets you create page builders that use your own components.
 
-## Demonstrates
+[Puck AI](https://puckeditor.com/docs/ai/overview) builds on the same principles to let you generate pages by assembling your existing components or creating new ones on the fly, either as a copilot in the editor or headlessly.
 
-- Puck AI integration for generating pages with AI
-- Next.js App Router implementation
-- JSON database implementation with HTTP API
-- Catch-all routes to use puck for any route on the platform
-- Incremental static regeneration (ISR) for all Puck pages
+This recipe connects Puck and Puck AI to the [Next.js App Router](https://nextjs.org/docs/app), so you can create and edit pages for any route in this app.
 
-## Usage
+## Core concepts
 
-Run the generator and select `Next.js` when prompted
+If you're new to Puck, this section introduces the core concepts you need to know.
 
-```
-npx create-puck-app my-app
+### Puck
 
-? Which recipe would you like to use?
-❯ Next.js
-```
+The Puck visual editor has three main parts: a config, the editor, and the renderer.
+
+#### Config
 
-Confirm you want to use Puck AI
+The [config](https://puckeditor.com/docs/integrating-puck/component-configuration) registers the components users can use to build pages in the editor and the fields they can edit.
 
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      fields: {
+        title: { type: "text" },
+      },
+      render: ({ title }) => <h1>{title}</h1>,
+    },
+  },
+};
 ```
-? Would you like to use Puck AI? (Y/n) Y
+
+#### The editor
+
+The [`<Puck>`](https://puckeditor.com/docs/api-reference/components/puck) component renders the editor. It uses a config, exports [pages as JSON](https://puckeditor.com/docs/api-reference/data-model/data), and accepts initial page data for editing existing pages.
+
+```tsx
+<Puck
+  config={config} // The components available to the editor
+  data={data} // The page JSON to edit
+  onPublish={(data) => {
+    // Save data to your database
+  }}
+/>
 ```
 
-Start the server
+#### The renderer
+
+The [`<Render>`](https://puckeditor.com/docs/api-reference/components/render) component renders pages. It expects the page JSON and the config used to create that page.
 
+```tsx
+<Render
+  config={config} // The components used to create the page
+  data={data} // The page JSON to render
+/>
 ```
-cd my-app
-yarn dev
+
+### Puck AI
+
+This recipe adds Puck AI as a copilot. It has two parts: the AI plugin (browser) and the Cloud Client (server).
+
+#### The AI plugin
+
+The [AI plugin](https://puckeditor.com/docs/api-reference/ai/ai-plugin/installation) renders the chat in the editor and sends each message to the Cloud Client on your server.
+
+```tsx
+const aiPlugin = createAiPlugin();
+
+function Editor() {
+  return <Puck plugins={[aiPlugin]} config={config} data={data} />;
+}
 ```
 
-### Set up Puck AI
+#### The Cloud Client
 
-Create a [Puck account](https://cloud.puckeditor.com) and [obtain an API key](https://cloud.puckeditor.com/api-keys).
+The [Cloud Client](https://puckeditor.com/docs/api-reference/ai/cloud-client/installation) provides APIs for connecting your server to the Puck cloud. This recipe uses its [`puckHandler`](https://puckeditor.com/docs/api-reference/ai/cloud-client/puck-handler) API, which receives each chat message, forwards it to the Puck cloud, and streams the response back to the plugin in the browser.
 
-Create a `.env.local` file in the root of your project and add your API key:
+```ts
+const handleRequest = (request: NextRequest) => {
+  return puckHandler(request, {
+    ai: {
+      context: "We are Google. You create Google landing pages.",
+    },
+  });
+};
 
+export const DELETE = handleRequest;
+export const GET = handleRequest;
+export const POST = handleRequest;
 ```
+
+#### Puck AI modes
+
+Puck AI can build pages in two ways:
+
+- **Assembly mode** only builds pages using components from your config.
+- **Design mode** can generate new components when needed.
+
+This recipe comes with [Design mode](https://puckeditor.com/docs/api-reference/ai/cloud-client/puck-handler#aidesignmode) enabled out of the box.
+
+## Run the recipe
+
+### 1. Add a Puck API key
+
+Start by creating an account, [generating an API key](https://cloud.puckeditor.com/api-keys), and adding it to a `.env.local` file:
+
+```sh
 PUCK_API_KEY=your-api-key
 ```
 
-Navigate to the homepage at https://localhost:3000. To edit the homepage, access the Puck editor at https://localhost:3000/edit, and select the AI button in the left navigation bar to generate content for the page using Puck AI.
+### 2. Start the development server
+
+Run:
+
+```sh
+npm run dev
+```
+
+Once the server is running, navigate to [http://localhost:3000](http://localhost:3000) to view the home page, or [http://localhost:3000/edit](http://localhost:3000/edit) to edit it with Puck.
+
+### 3. Create a page with Puck AI
+
+Navigate to [http://localhost:3000/edit](http://localhost:3000/edit), click the **AI** button in the left sidebar, enter a prompt, and press Enter.
+
+### 4. Publish the page
+
+Once your page is ready, select **Publish** in the header to save the result, then navigate to [http://localhost:3000](http://localhost:3000) to view the published page.
+
+You can also create a page at any path by navigating to `/your/path/edit` and publishing it. The route `/your/path` will render the page.
+
+## How it works
+
+When a URL ends in `/edit`, [`proxy.ts`](https://nextjs.org/docs/app/api-reference/file-conventions/proxy) sends the request to the Puck editor route (`app/puck/[...puckPath]/page.tsx`). The editor loads the saved page, or starts with an empty page if the path is new.
+
+Selecting **Publish** sends the page data to the `/api/pages` endpoint (`app/api/pages/route.ts`). The handler writes the JSON to `database.json` and clears the Next.js cache for that page. The catch-all route (`app/[...puckPath]/page.tsx`) then loads the same data and renders it with [`<Render>`](https://puckeditor.com/docs/api-reference/components/render).
+
+The table below shows the files that implement this flow.
+
+| File                                | Purpose                                                                                                              |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `puck.config.tsx`                   | Defines the components, fields, and default props available to Puck and Assembly mode. Add your own components here. |
+| `app/puck/[...puckPath]/page.tsx`   | Loads page data for the editor.                                                                                      |
+| `app/puck/[...puckPath]/client.tsx` | Renders the editor with the AI copilot, sends prompts to your server, and publishes changes.                         |
+| `app/[...puckPath]/page.tsx`        | Loads and renders published pages.                                                                                   |
+| `app/api/pages/route.ts`            | Saves published pages.                                                                                               |
+| `app/api/puck/[...all]/route.ts`    | Handles requests from the AI plugin and configures AI generation.                                                    |
+| `proxy.ts`                          | Routes URLs ending in `/edit` to `/puck/[...puckPath]/page.tsx`.                                                     |
+| `lib/get-page.ts`                   | Reads page data from `database.json`. Replace this with your own data fetching logic.                                |
+| `database.json`                     | Acts as a local database. Replace this with your own database solution.                                              |
 
-You can do this for any route on the application, **even if the page doesn't exist**. For example, visit https://localhost:3000/hello/world and you'll receive a 404. You can author and publish a page by visiting https://localhost:3000/hello/world/edit. After publishing, go back to the original URL to see your page.
+## Before deploying to production
 
-## Using this recipe
+Before deploying this recipe, make sure to:
 
-To adopt this recipe you will need to:
+- **Protect the editor and APIs.** The `/edit`, `/api/pages`, and `/api/puck` routes are public by default. Add authentication, authorization, and rate limits to protect page data and AI usage.
+- **Add your component library.** Replace the example `HeadingBlock` in `puck.config.tsx` with the components and fields your users need.
+- **Set your business context.** Replace the example Google context in `app/api/puck/[...all]/route.ts` with clear information about your product, audience, and content rules.
+- **Use a real database.** Replace `database.json` in `lib/get-page.ts` and `app/api/pages/route.ts`. Local files are not reliable across server instances or serverless deployments.
+- **Choose a rendering strategy.** `app/[...puckPath]/page.tsx` uses `force-static`. Remove it if a page needs request-time data such as headers, cookies, or user sessions.
 
-- **IMPORTANT** Add authentication to `/edit` routes. This can be done by modifying the example API routes in `/app/puck/api/route.ts` and server component in `/app/puck/[...puckPath]/page.tsx`. **If you don't do this, Puck will be completely public.**
-- Integrate your database into the API calls in `/app/puck/api/route.ts`
-- Implement a custom puck configuration in `puck.config.tsx`
-- Add business context for the AI generation in `/app/api/puck/[...all]/route.ts`
+## Learn more
 
-By default, this recipe will generate static pages by setting `dynamic` to [`force-static`](https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config#dynamic) in the `/app/[...puckPath]/page.tsx`. This will strip headers and cookies. If you need dynamic pages, you can delete this.
+- [Puck documentation](https://puckeditor.com/docs)
+- [Getting started with Puck](https://puckeditor.com/docs/getting-started)
+- [Integrating Puck](https://puckeditor.com/docs/integrating-puck/component-configuration)
+- [Puck AI documentation](https://puckeditor.com/docs/ai/overview)
+- [Getting started with Puck AI](https://puckeditor.com/docs/ai/getting-started)
+- [Puck Discord](https://discord.gg/D9e4E3MQVZ)

package/templates/next-ai/app/[...puckPath]/client.tsx

@@ -2,8 +2,11 @@
 
 import type { Data } from "@puckeditor/core";
 import { Render } from "@puckeditor/core";
+import { withDynamicConfig } from "@puckeditor/plugin-ai";
 import config from "../../puck.config";
 
 export function Client({ data }: { data: Data }) {
-  return <Render config={config} data={data} />;
+  const configWithDesignedComponents = withDynamicConfig(config, data);
+
+  return <Render config={configWithDesignedComponents} data={data} />;
 }

package/templates/next-ai/app/api/puck/[...all]/route.ts

@@ -1,12 +1,27 @@
 // Handles all requests for Puck AI
 // Learn more: https://puckeditor.com/docs/ai/getting-started
+import type { NextRequest } from "next/server";
 import { puckHandler } from "@puckeditor/cloud-client";
 
-const handleRequest = (request) => {
+const handleRequest = (request: NextRequest): Promise<Response> => {
   return puckHandler(request, {
     ai: {
       // Replace with your business context
       context: "We are Google. You create Google landing pages.",
+      designMode: {
+        // Allow AI to generate new components using "design mode"
+        // Learn more: https://puckeditor.com/docs/ai/design-mode
+        allowed: true,
+        // Constrain component generation, replace with your own instructions
+        instructions: `
+        #### Color Palette
+
+        Always use the following colors:
+
+        * Primary: \`#1976d2\`
+        * Secondary: \`#9c27b0\`
+        `,
+      },
     },
   });
 };

package/templates/next-ai/app/puck/[...puckPath]/client.tsx

@@ -1,19 +1,32 @@
 "use client";
 
 import type { Data } from "@puckeditor/core";
-import { Puck } from "@puckeditor/core";
-import { createAiPlugin } from "@puckeditor/plugin-ai";
+import { Puck, blocksPlugin, outlinePlugin } from "@puckeditor/core";
+import { createAiPlugin, withDynamicConfig } from "@puckeditor/plugin-ai";
 
 import config from "../../../puck.config";
 
-const aiPlugin = createAiPlugin();
+const aiPlugin = createAiPlugin({
+  // Allow users to switch between design and assembly mode.
+  // Read more: https://puckeditor.com/docs/ai/design-mode
+  designMode: {
+    visible: true,
+  },
+  // Select design mode by default.
+  defaultMode: "design",
+});
+
+// Place the ai plugin in the first position in the side nav.
+const plugins = [aiPlugin, blocksPlugin(), outlinePlugin()];
 
 export function Client({ path, data }: { path: string; data: Partial<Data> }) {
+  const configWithDesignedComponents = withDynamicConfig(config, data);
+
   return (
     <Puck
-      plugins={[aiPlugin]}
-      config={config}
+      plugins={plugins}
       data={data}
+      config={configWithDesignedComponents}
       onPublish={async (data) => {
         await fetch("/api/pages", {
           method: "post",

package/templates/react-router/README.md

@@ -1,35 +1,113 @@
-# `react-router` recipe
+# Puck + React Router recipe
 
-The `react-router` recipe showcases one of the most powerful ways to implement Puck using to provide an authoring tool for any route in your React Router app.
+[Puck](https://puckeditor.com) is the open-source visual editor for React.
 
-## Demonstrates
+This recipe connects Puck to [React Router](https://reactrouter.com) in framework mode, so you can create and edit pages for any route in this app.
 
-- React Router v7 (framework) implementation
-- JSON database implementation
-- Splat route to use puck for any route on the platform
+## Core concepts
 
-## Usage
+If you're new to Puck, this section introduces the core concepts you need to know.
 
-Run the generator and enter `react-router` when prompted
+### Puck
 
+The Puck visual editor has three main parts: a config, the editor, and the renderer.
+
+#### Config
+
+The [config](https://puckeditor.com/docs/integrating-puck/component-configuration) registers the components users can use to build pages in the editor and the fields they can edit.
+
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      fields: {
+        title: { type: "text" },
+      },
+      render: ({ title }) => <h1>{title}</h1>,
+    },
+  },
+};
 ```
-npx create-puck-app my-app
+
+#### The editor
+
+The [`<Puck>`](https://puckeditor.com/docs/api-reference/components/puck) component renders the editor. It uses a config, exports [pages as JSON](https://puckeditor.com/docs/api-reference/data-model/data), and accepts initial page data for editing existing pages.
+
+```tsx
+<Puck
+  config={config} // The components available to the editor
+  data={data} // The page JSON to edit
+  onPublish={(data) => {
+    // Save data to your database
+  }}
+/>
 ```
 
-Start the server
+#### The renderer
 
+The [`<Render>`](https://puckeditor.com/docs/api-reference/components/render) component renders pages. It expects the page JSON and the config used to create that page.
+
+```tsx
+<Render
+  config={config} // The components used to create the page
+  data={data} // The page JSON to render
+/>
 ```
-yarn dev
+
+## Run the recipe
+
+### 1. Start the development server
+
+Run:
+
+```sh
+npm run dev
 ```
 
-Navigate to the homepage at http://localhost:5173/. To edit the homepage, access the Puck editor at http://localhost:5173/edit.
+Once the server is running, navigate to [http://localhost:5173](http://localhost:5173) to view the home page, or [http://localhost:5173/edit](http://localhost:5173/edit) to edit it with Puck.
+
+### 2. Create a page
+
+Navigate to [http://localhost:5173/edit](http://localhost:5173/edit), open the `Blocks` tab in the left sidebar and build your page by dragging components onto the canvas.
+
+### 3. Publish the page
+
+Once your page is ready, select **Publish** in the header to save the result, then navigate to [http://localhost:5173](http://localhost:5173) to view the published page.
+
+You can also create a page at any path by navigating to `/your/path/edit` and publishing it. The route `/your/path` will render the page.
+
+## How it works
+
+When a URL ends in `/edit`, `resolvePuckPath` (`app/lib/resolve-puck-path.server.ts`) returns the path of the page being edited. The loader in `app/routes/puck-splat.tsx` loads the saved page, or starts with an empty page if the path is new.
+
+Selecting **Publish** sends the page data to the action in `app/routes/puck-splat.tsx`. The action writes the JSON to `database.json`. The route then loads the same data and renders it with [`<Render>`](https://puckeditor.com/docs/api-reference/components/render).
+
+The table below shows the files that implement this flow.
+
+| File                                  | Purpose                                                                                                   |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `puck.config.tsx`                     | Defines the components, fields, and default props available to Puck. Add your own components here.        |
+| `app/routes.ts`                       | Registers the home page and catch-all page route.                                                         |
+| `app/routes/puck-splat.tsx`           | Loads and saves page data, then renders the editor or published page.                                     |
+| `app/routes/_index.tsx`               | Loads and renders the home page.                                                                          |
+| `app/lib/resolve-puck-path.server.ts` | Maps an `/edit` URL to the path of the page being edited.                                                 |
+| `app/lib/pages.server.ts`             | Reads and writes page data in `database.json`. Replace this with your own data fetching and saving logic. |
+| `app/components/puck-render.tsx`      | Renders saved page data with `<Render>`.                                                                  |
+| `database.json`                       | Acts as a local database. Replace this with your own database solution.                                   |
+
+## Before deploying to production
 
-You can do this for any **base** route on the application, **even if the page doesn't exist**. For example, visit http://localhost:5173/hello-world and you'll receive a 404. You can author and publish a page by visiting http://localhost:5173/hello-world/edit. After publishing, go back to the original URL to see your page.
+Before deploying this recipe, make sure to:
 
-## Using this recipe
+- **Protect the editor and publishing.** The `/edit` routes and publish action are public by default. Add authentication and authorization so only trusted users can edit or publish pages.
+- **Add your component library.** Replace the example `HeadingBlock` in `puck.config.tsx` with the components and fields your users need.
+- **Use a real database.** Replace `database.json` and the functions in `app/lib/pages.server.ts`. Local files are not reliable across server instances or serverless deployments.
+- **Choose a deployment strategy.** This recipe uses server-side rendering, loaders, and actions. Deploy it to a React Router-compatible server runtime.
 
-To adopt this recipe, you will need to:
+## Learn more
 
-- **IMPORTANT** Add authentication to `/edit` routes. This can be done by modifying the [route module action](https://reactrouter.com/start/framework/route-module#action) in the splat route `/app/routes/puck-splat.tsx`. **If you don't do this, Puck will be completely public.**
-- Integrate your database into the functions in `/lib/pages.server.ts`
-- Implement a custom puck configuration in `/app/puck.config.tsx`
+- [Puck documentation](https://puckeditor.com/docs)
+- [Getting started with Puck](https://puckeditor.com/docs/getting-started)
+- [Integrating Puck](https://puckeditor.com/docs/integrating-puck/component-configuration)
+- [React Router framework mode](https://reactrouter.com/start/framework/installation)
+- [Puck Discord](https://discord.gg/D9e4E3MQVZ)

package/templates/react-router-ai/README.md

@@ -1,57 +1,172 @@
-# `react-router-ai` recipe
+# Puck AI + React Router recipe
 
-The `react-router-ai` recipe showcases one of the most powerful ways to combine Puck and [Puck AI](https://puckeditor.com/docs/ai/overview): providing an authoring tool with AI page generation capabilities for any route in your React Router app.
+[Puck](https://puckeditor.com) is the open-source visual editor for React. It lets you create page builders that use your own components.
 
-## Demonstrates
+[Puck AI](https://puckeditor.com/docs/ai/overview) builds on the same principles to let you generate pages by assembling your existing components or creating new ones on the fly, either as a copilot in the editor or headlessly.
 
-- Puck AI integration for generating pages with AI
-- React Router v7 (framework) implementation
-- JSON database implementation
-- Splat route to use puck for any route on the platform
+This recipe connects Puck and Puck AI to [React Router](https://reactrouter.com) in framework mode, so you can create and edit pages for any route in this app.
 
-## Usage
+## Core concepts
 
-Run the generator and select `React Router` when prompted
+If you're new to Puck, this section introduces the core concepts you need to know.
 
-```
-npx create-puck-app my-app
+### Puck
 
-? Which recipe would you like to use?
-❯ React Router
-```
+The Puck visual editor has three main parts: a config, the editor, and the renderer.
+
+#### Config
 
-Confirm you want to use Puck AI
+The [config](https://puckeditor.com/docs/integrating-puck/component-configuration) registers the components users can use to build pages in the editor and the fields they can edit.
 
+```tsx
+const config = {
+  components: {
+    HeadingBlock: {
+      fields: {
+        title: { type: "text" },
+      },
+      render: ({ title }) => <h1>{title}</h1>,
+    },
+  },
+};
 ```
-? Would you like to use Puck AI? (Y/n) Y
+
+#### The editor
+
+The [`<Puck>`](https://puckeditor.com/docs/api-reference/components/puck) component renders the editor. It uses a config, exports [pages as JSON](https://puckeditor.com/docs/api-reference/data-model/data), and accepts initial page data for editing existing pages.
+
+```tsx
+<Puck
+  config={config} // The components available to the editor
+  data={data} // The page JSON to edit
+  onPublish={(data) => {
+    // Save data to your database
+  }}
+/>
 ```
 
-Start the server
+#### The renderer
+
+The [`<Render>`](https://puckeditor.com/docs/api-reference/components/render) component renders pages. It expects the page JSON and the config used to create that page.
 
+```tsx
+<Render
+  config={config} // The components used to create the page
+  data={data} // The page JSON to render
+/>
 ```
-cd my-app
-yarn dev
+
+### Puck AI
+
+This recipe adds Puck AI as a copilot. It has two parts: the AI plugin (browser) and the Cloud Client (server).
+
+#### The AI plugin
+
+The [AI plugin](https://puckeditor.com/docs/api-reference/ai/ai-plugin/installation) renders the chat in the editor and sends each message to the Cloud Client on your server.
+
+```tsx
+const aiPlugin = createAiPlugin();
+
+function Editor() {
+  return <Puck plugins={[aiPlugin]} config={config} data={data} />;
+}
 ```
 
-### Set up Puck AI
+#### The Cloud Client
 
-Create a [Puck account](https://cloud.puckeditor.com) and [obtain an API key](https://cloud.puckeditor.com/api-keys).
+The [Cloud Client](https://puckeditor.com/docs/api-reference/ai/cloud-client/installation) provides APIs for connecting your server to the Puck cloud. This recipe uses its [`puckHandler`](https://puckeditor.com/docs/api-reference/ai/cloud-client/puck-handler) API, which receives each chat message, forwards it to the Puck cloud, and streams the response back to the plugin in the browser.
 
-Create a `.env.local` file in the root of your project and add your API key:
+```ts
+const options = {
+  ai: {
+    context: "We are Google. You create Google landing pages.",
+  },
+};
 
+export function loader(args: LoaderFunctionArgs) {
+  return puckHandler(args.request, options);
+}
+
+export function action(args: ActionFunctionArgs) {
+  return puckHandler(args.request, options);
+}
 ```
+
+#### Puck AI modes
+
+Puck AI can build pages in two ways:
+
+- **Assembly mode** only builds pages using components from your config.
+- **Design mode** can generate new components when needed.
+
+This recipe comes with [Design mode](https://puckeditor.com/docs/api-reference/ai/cloud-client/puck-handler#aidesignmode) enabled out of the box.
+
+## Run the recipe
+
+### 1. Add a Puck API key
+
+Start by creating an account, [generating an API key](https://cloud.puckeditor.com/api-keys), and adding it to an `.env.local` file:
+
+```sh
 PUCK_API_KEY=your-api-key
 ```
 
-Navigate to the homepage at https://localhost:3000. To edit the homepage, access the Puck editor at https://localhost:3000/edit, and select the AI button in the left navigation bar to generate content for the page using Puck AI.
+### 2. Start the development server
+
+Run:
+
+```sh
+npm run dev
+```
+
+Once the server is running, navigate to [http://localhost:5173](http://localhost:5173) to view the home page, or [http://localhost:5173/edit](http://localhost:5173/edit) to edit it with Puck.
+
+### 3. Create a page with Puck AI
+
+Navigate to [http://localhost:5173/edit](http://localhost:5173/edit), click the **AI** button in the left sidebar, enter a prompt, and press Enter.
+
+### 4. Publish the page
+
+Once your page is ready, select **Publish** in the header to save the result, then navigate to [http://localhost:5173](http://localhost:5173) to view the published page.
+
+You can also create a page at any path by navigating to `/your/path/edit` and publishing it. The route `/your/path` will render the page.
+
+## How it works
+
+When a URL ends in `/edit`, `resolvePuckPath` (`app/lib/resolve-puck-path.server.ts`) returns the path of the page being edited. The loader in `app/routes/puck-splat.tsx` loads the saved page, or starts with an empty page if the path is new.
+
+Selecting **Publish** sends the page data to the action in `app/routes/puck-splat.tsx`. The action writes the JSON to `database.json`. The route then loads the same data and renders it with [`<Render>`](https://puckeditor.com/docs/api-reference/components/render).
+
+The table below shows the files that implement this flow.
+
+| File                                  | Purpose                                                                                                              |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `puck.config.tsx`                     | Defines the components, fields, and default props available to Puck and Assembly mode. Add your own components here. |
+| `app/routes.ts`                       | Registers the home page, Puck AI API, and catch-all page route.                                                      |
+| `app/routes/puck-splat.tsx`           | Loads and saves page data, then renders the editor or published page.                                                |
+| `app/routes/api.puck.ts`              | Handles requests from the AI plugin and configures AI generation.                                                    |
+| `app/routes/_index.tsx`               | Loads and renders the home page.                                                                                     |
+| `app/lib/resolve-puck-path.server.ts` | Maps an `/edit` URL to the path of the page being edited.                                                            |
+| `app/lib/pages.server.ts`             | Reads and writes page data in `database.json`. Replace this with your own data fetching and saving logic.            |
+| `app/components/puck-render.tsx`      | Renders saved page data with `<Render>`.                                                                             |
+| `database.json`                       | Acts as a local database. Replace this with your own database solution.                                              |
+
+## Before deploying to production
 
-You can do this for any route on the application, **even if the page doesn't exist**. For example, visit https://localhost:3000/hello/world and you'll receive a 404. You can author and publish a page by visiting https://localhost:3000/hello/world/edit. After publishing, go back to the original URL to see your page.
+Before deploying this recipe, make sure to:
 
-## Using this recipe
+- **Protect the editor and APIs.** The `/edit` routes, publish action, and `/api/puck` route are public by default. Add authentication, authorization, and rate limits to protect page data and AI usage.
+- **Add your component library.** Replace the example `HeadingBlock` in `puck.config.tsx` with the components and fields your users need.
+- **Set your business context.** Replace the example Google context in `app/routes/api.puck.ts` with clear information about your product, audience, and content rules.
+- **Use a real database.** Replace `database.json` and the functions in `app/lib/pages.server.ts`. Local files are not reliable across server instances or serverless deployments.
+- **Choose a deployment strategy.** This recipe uses server-side rendering, loaders, and actions. Deploy it to a React Router-compatible server runtime.
 
-To adopt this recipe, you will need to:
+## Learn more
 
-- **IMPORTANT** Add authentication to `/edit` routes. This can be done by modifying the [route module action](https://reactrouter.com/start/framework/route-module#action) in the splat route `/app/routes/puck-splat.tsx`. **If you don't do this, Puck will be completely public.**
-- Integrate your database into the functions in `/lib/pages.server.ts`
-- Implement a custom puck configuration in `/app/puck.config.tsx`
-- Add business context for the AI generation in `/app/routes/api.puck.ts`
+- [Puck documentation](https://puckeditor.com/docs)
+- [Getting started with Puck](https://puckeditor.com/docs/getting-started)
+- [Integrating Puck](https://puckeditor.com/docs/integrating-puck/component-configuration)
+- [Puck AI documentation](https://puckeditor.com/docs/ai/overview)
+- [Getting started with Puck AI](https://puckeditor.com/docs/ai/getting-started)
+- [React Router framework mode](https://reactrouter.com/start/framework/installation)
+- [Puck Discord](https://discord.gg/D9e4E3MQVZ)

package/templates/react-router-ai/app/components/puck-render.tsx

@@ -1,8 +1,11 @@
 import type { Data } from "@puckeditor/core";
 import { Render } from "@puckeditor/core";
+import { withDynamicConfig } from "@puckeditor/plugin-ai";
 
 import { config } from "../../puck.config";
 
 export function PuckRender({ data }: { data: Data }) {
-  return <Render config={config} data={data} />;
+  const configWithDesignedComponents = withDynamicConfig(config, data);
+
+  return <Render config={configWithDesignedComponents} data={data} />;
 }

package/templates/react-router-ai/app/routes/api.puck.ts

@@ -8,6 +8,20 @@ const options: PuckCloudOptions = {
   ai: {
     // Replace with your business context
     context: "We are Google. You create Google landing pages.",
+    designMode: {
+      // Allow AI to generate new components using "design mode"
+      // Learn more: https://puckeditor.com/docs/ai/design-mode
+      allowed: true,
+      // Constrain component generation, replace with your own instructions
+      instructions: `
+      #### Color Palette
+
+      Always use the following colors:
+
+      * Primary: \`#1976d2\`
+      * Secondary: \`#9c27b0\`
+      `,
+    },
   },
 };
 

package/templates/react-router-ai/app/routes/puck-splat.tsx

@@ -1,12 +1,15 @@
+import { useMemo } from "react";
 import { useFetcher, useLoaderData } from "react-router";
 import type { Data } from "@puckeditor/core";
-import { Puck, Render } from "@puckeditor/core";
-import { createAiPlugin } from "@puckeditor/plugin-ai";
+import { Puck, blocksPlugin, outlinePlugin } from "@puckeditor/core";
+import { createAiPlugin, withDynamicConfig } from "@puckeditor/plugin-ai";
 
 import type { Route } from "./+types/puck-splat";
 import { config } from "../../puck.config";
 import { resolvePuckPath } from "~/lib/resolve-puck-path.server";
 import { getPage, savePage } from "~/lib/pages.server";
+import { PuckRender } from "~/components/puck-render";
+
 import editorStyles from "@puckeditor/core/puck.css?url";
 import pluginStyles from "@puckeditor/plugin-ai/styles.css?url";
 
@@ -57,19 +60,35 @@ export async function action({ params, request }: Route.ActionArgs) {
   await savePage(path, body.data);
 }
 
-const aiPlugin = createAiPlugin();
+const aiPlugin = createAiPlugin({
+  // Allow users to switch between design and assembly mode.
+  // Read more: https://puckeditor.com/docs/ai/design-mode
+  designMode: {
+    visible: true,
+  },
+  // Select design mode by default.
+  defaultMode: "design",
+});
+
+// Place the ai plugin in the first position in the side nav.
+const plugins = [aiPlugin, blocksPlugin(), outlinePlugin()];
 
 function Editor() {
   const loaderData = useLoaderData<typeof loader>();
   const fetcher = useFetcher<typeof action>();
 
+  const configWithDesignedComponents = useMemo(
+    () => withDynamicConfig(config, loaderData.data),
+    [config, loaderData.data]
+  );
+
   return (
     <>
       <link rel="stylesheet" href={editorStyles} id="puck-css" />
       <link rel="stylesheet" href={pluginStyles} id="puck-plugin-ai-css" />
       <Puck
-        plugins={[aiPlugin]}
-        config={config}
+        plugins={plugins}
+        config={configWithDesignedComponents}
         data={loaderData.data}
         onPublish={async (data) => {
           await fetcher.submit(
@@ -94,7 +113,7 @@ export default function PuckSplatRoute({ loaderData }: Route.ComponentProps) {
       {loaderData.isEditorRoute ? (
         <Editor />
       ) : (
-        <Render config={config} data={loaderData.data} />
+        <PuckRender data={loaderData.data} />
       )}
     </div>
   );