@puckeditor/cli 0.24.0-canary.301a0304

package/dist/templates/astro-ai/src/pages/api/puck/[...all].ts

@@ -0,0 +1,36 @@
+// Handles all requests for Puck AI
+// Learn more: https://puckeditor.com/docs/ai/getting-started
+import fs from "node:fs";
+import type { APIRoute } from "astro";
+import type { PuckCloudOptions } from "@puckeditor/cloud-client";
+import { puckHandler } from "@puckeditor/cloud-client";
+
+export const prerender = false;
+
+// Astro doesn't put .env files in process.env, where puckHandler reads
+// PUCK_API_KEY. Production servers read it from their environment.
+if (import.meta.env.DEV && fs.existsSync(".env.local"))
+  process.loadEnvFile(".env.local");
+
+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\`
+      `,
+    },
+  },
+};
+
+export const ALL: APIRoute = ({ request }) => puckHandler(request, options);

package/dist/templates/astro-ai/src/puck/editor.tsx

@@ -0,0 +1,53 @@
+import { useEffect, useMemo, useState } from "react";
+import type { Data } from "@puckeditor/core";
+import { Puck, blocksPlugin, outlinePlugin } from "@puckeditor/core";
+import { createAiPlugin, withDynamicConfig } from "@puckeditor/plugin-ai";
+import "@puckeditor/core/puck.css";
+import "@puckeditor/plugin-ai/styles.css";
+
+import { config } from "../puck.config";
+import { loadPage, savePage } from "./pages";
+
+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()];
+
+// Empty shell for new pages
+const emptyPage: Data = { content: [], root: { props: { title: "" } } };
+
+// e.g. /edit?path=/about, where there are no server routes for each page
+const pathFromQuery = () =>
+  new URLSearchParams(window.location.search).get("path") ?? "/";
+
+export default function Editor({ path = pathFromQuery() }: { path?: string }) {
+  const [data, setData] = useState<Data | null>(null);
+
+  useEffect(() => {
+    loadPage(path).then((page) => setData(page ?? emptyPage));
+  }, [path]);
+
+  const configWithDesignedComponents = useMemo(
+    () => (data ? withDynamicConfig(config, data) : config),
+    [data]
+  );
+
+  if (!data) return null;
+
+  return (
+    <Puck
+      plugins={plugins}
+      config={configWithDesignedComponents}
+      data={data}
+      onPublish={(data) => savePage(path, data)}
+    />
+  );
+}

package/dist/templates/astro-ai/src/puck/pages.ts

@@ -0,0 +1,15 @@
+import type { Data } from "@puckeditor/core";
+
+// Loads and saves pages with the pages API in server/puck/pages.ts
+export const loadPage = async (path: string): Promise<Data | null> => {
+  const response = await fetch(`/api/pages?path=${encodeURIComponent(path)}`);
+  return response.ok ? response.json() : null;
+};
+
+export const savePage = async (path: string, data: Data) => {
+  await fetch("/api/pages", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ path, data }),
+  });
+};

package/dist/templates/astro-ai/src/puck/render.tsx

@@ -0,0 +1,10 @@
+import type { Data } from "@puckeditor/core";
+import { Render } from "@puckeditor/core";
+import { withDynamicConfig } from "@puckeditor/plugin-ai";
+
+import { config } from "../puck.config";
+
+// Rendered on the server, without shipping the editor to the browser
+export default function PuckRender({ data }: { data: Data }) {
+  return <Render config={withDynamicConfig(config, data)} data={data} />;
+}

package/dist/templates/astro-ai/src/puck.config.tsx

@@ -0,0 +1,23 @@
+import type { Config } from "@puckeditor/core";
+
+type Props = {
+  HeadingBlock: { title: string };
+};
+
+export const config: Config<Props> = {
+  components: {
+    HeadingBlock: {
+      fields: {
+        title: { type: "text" },
+      },
+      defaultProps: {
+        title: "Heading",
+      },
+      render: ({ title }) => (
+        <div style={{ padding: 64 }}>
+          <h1>{title}</h1>
+        </div>
+      ),
+    },
+  },
+};

package/dist/templates/astro-ai/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "include": [
+    ".astro/types.d.ts",
+    "**/*"
+  ],
+  "exclude": [
+    "dist"
+  ],
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "react"
+  }
+}

package/dist/templates/express/README.md

@@ -0,0 +1,66 @@
+# Puck + Express recipe
+
+[Puck](https://puckeditor.com) is the open-source visual editor for React.
+
+This recipe is a [Express](https://expressjs.com) server that stores Puck pages. It has no editor of its own: point a Puck editor in your React app at it.
+
+## The APIs
+
+| Route                        | Purpose                                           |
+| ---------------------------- | ------------------------------------------------- |
+| `GET /api/pages?path=/about` | Returns the saved page data for a path, or a 404. |
+| `POST /api/pages`            | Saves `{ "path": "/about", "data": { ... } }`.    |
+
+## Run the recipe
+
+### 1. Start the server
+
+Run:
+
+```sh
+npm run dev
+```
+
+Once the server is running, [http://localhost:3000/api/pages?path=/](http://localhost:3000/api/pages?path=/) returns the home page's data.
+
+### 2. Connect an editor
+
+Load and save pages from your editor with the pages API:
+
+```tsx
+<Puck
+  config={config}
+  data={await(await fetch("/api/pages?path=/")).json()}
+  onPublish={(data) =>
+    fetch("/api/pages", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ path: "/", data }),
+    })
+  }
+/>
+```
+
+If your editor runs on another origin, proxy `/api` to this server in development (for example with Vite's [`server.proxy`](https://vite.dev/config/server-options#server-proxy)), or enable CORS.
+
+## How it works
+
+| File                | Purpose                                                                             |
+| ------------------- | ----------------------------------------------------------------------------------- |
+| `src/index.ts`      | Creates the Express app and mounts the Puck routes with `app.use(puckPages);`.      |
+| `src/puck/pages.ts` | Reads and writes page data in `database.json`. Replace this with your own database. |
+| `database.json`     | Acts as a local database. Replace this with your own database solution.             |
+
+## Before deploying to production
+
+Before deploying this recipe, make sure to:
+
+- **Protect the APIs.** The pages API is public by default. Add authentication, authorization to protect page data.
+- **Use a real database.** Replace `database.json` and `src/puck/pages.ts`. Local files are not reliable across server instances or serverless deployments.
+
+## Learn more
+
+- [Puck documentation](https://puckeditor.com/docs)
+- [Integrating Puck](https://puckeditor.com/docs/integrating-puck/component-configuration)
+- [Express](https://expressjs.com)
+- [Puck Discord](https://discord.gg/D9e4E3MQVZ)

package/dist/templates/express/_gitignore

@@ -0,0 +1,16 @@
+# deps
+node_modules/
+
+# build
+dist/
+
+# env
+.env
+.env.local
+.env.production
+
+# logs
+*.log
+
+# misc
+.DS_Store

package/dist/templates/express/database.json

@@ -0,0 +1 @@
+{"/":{"content":[{"type":"HeadingBlock","props":{"title":"Edit this page by adding /edit to the end of the URL","id":"HeadingBlock-1694032984497"}}],"root":{"props": {"title":""}}}}

package/dist/templates/express/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "express-recipe",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "express": "^5.2.1"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.3",
+    "@types/node": "^22.10.2",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.3"
+  }
+}

package/dist/templates/express/src/index.ts

@@ -0,0 +1,15 @@
+import express from "express";
+import { puckPages } from "./puck/pages.js";
+
+const app = express();
+app.use(express.json());
+
+app.get("/", (_req, res) => {
+  res.send("Hello Express!");
+});
+
+app.use(puckPages);
+
+app.listen(3000, () => {
+  console.log("Server is running on http://localhost:3000");
+});

package/dist/templates/express/src/puck/pages.ts

@@ -0,0 +1,39 @@
+// Loads and saves Puck pages for the editor
+// Learn more: https://puckeditor.com/docs/cli
+import fs from "node:fs/promises";
+import express from "express";
+
+// Replace this with your own database
+const databasePath = "database.json";
+
+const readPages = async (): Promise<Record<string, unknown>> => {
+  try {
+    return JSON.parse(await fs.readFile(databasePath, "utf-8"));
+  } catch {
+    return {};
+  }
+};
+
+export const puckPages = express.Router();
+
+puckPages.get("/api/pages", async (req, res) => {
+  const pages = await readPages();
+  const page = pages[typeof req.query.path === "string" ? req.query.path : "/"];
+
+  if (page) res.json(page);
+  else res.status(404).json({ error: "Not found" });
+});
+
+puckPages.post(
+  "/api/pages",
+  express.json({ limit: "10mb" }),
+  async (req, res) => {
+    const { path, data } = req.body;
+    const pages = await readPages();
+
+    pages[path] = data;
+    await fs.writeFile(databasePath, JSON.stringify(pages));
+
+    res.json({ status: "ok" });
+  }
+);

package/dist/templates/express/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  }
+}

package/dist/templates/express-ai/README.md

@@ -0,0 +1,81 @@
+# Puck AI + Express recipe
+
+[Puck](https://puckeditor.com) is the open-source visual editor for React.
+
+This recipe is a [Express](https://expressjs.com) server that stores Puck pages and serves Puck AI. It has no editor of its own: point a Puck editor in your React app at it, and add the Puck AI plugin to that editor.
+
+## The APIs
+
+| Route                        | Purpose                                                                                                                                                |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `GET /api/pages?path=/about` | Returns the saved page data for a path, or a 404.                                                                                                      |
+| `POST /api/pages`            | Saves `{ "path": "/about", "data": { ... } }`.                                                                                                         |
+| `/api/puck/*`                | Forwards requests from the Puck AI plugin to Puck Cloud using [`puckHandler`](https://puckeditor.com/docs/api-reference/ai/cloud-client/puck-handler). |
+
+## 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
+```
+
+### 2. Start the server
+
+Run:
+
+```sh
+npm run dev
+```
+
+Once the server is running, [http://localhost:3000/api/pages?path=/](http://localhost:3000/api/pages?path=/) returns the home page's data.
+
+### 3. Connect an editor
+
+Load and save pages from your editor with the pages API:
+
+```tsx
+<Puck
+  config={config}
+  data={await(await fetch("/api/pages?path=/")).json()}
+  onPublish={(data) =>
+    fetch("/api/pages", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ path: "/", data }),
+    })
+  }
+/>
+```
+
+If your editor runs on another origin, proxy `/api` to this server in development (for example with Vite's [`server.proxy`](https://vite.dev/config/server-options#server-proxy)), or enable CORS.
+
+The [Puck AI plugin](https://puckeditor.com/docs/api-reference/ai/ai-plugin/installation) calls `/api/puck` on the editor's origin by default. Pass `host` to `createAiPlugin` to call this server directly instead.
+
+## How it works
+
+| File                | Purpose                                                                                                  |
+| ------------------- | -------------------------------------------------------------------------------------------------------- |
+| `src/index.ts`      | Creates the Express app and mounts the Puck routes with `app.use(puckPages);` and `app.use(puckCloud);`. |
+| `src/puck/pages.ts` | Reads and writes page data in `database.json`. Replace this with your own database.                      |
+| `src/puck/cloud.ts` | Handles requests from the AI plugin and configures AI generation.                                        |
+| `database.json`     | Acts as a local database. Replace this with your own database solution.                                  |
+
+## Before deploying to production
+
+Before deploying this recipe, make sure to:
+
+- **Protect the APIs.** The pages API and `/api/puck` route are public by default. Add authentication, authorization, and rate limits to protect page data and AI usage.
+- **Set your business context.** Replace the example Google context in `src/puck/cloud.ts` with clear information about your product, audience, and content rules.
+- **Set `PUCK_API_KEY` in production.** `npm start` runs Node without `.env.local`, so set it in the environment wherever the server runs.
+- **Use a real database.** Replace `database.json` and `src/puck/pages.ts`. Local files are not reliable across server instances or serverless deployments.
+
+## Learn more
+
+- [Puck documentation](https://puckeditor.com/docs)
+- [Integrating Puck](https://puckeditor.com/docs/integrating-puck/component-configuration)
+- [Puck AI documentation](https://puckeditor.com/docs/ai/overview)
+- [Express](https://expressjs.com)
+- [Puck Discord](https://discord.gg/D9e4E3MQVZ)

package/dist/templates/express-ai/_gitignore

@@ -0,0 +1,16 @@
+# deps
+node_modules/
+
+# build
+dist/
+
+# env
+.env
+.env.local
+.env.production
+
+# logs
+*.log
+
+# misc
+.DS_Store

package/dist/templates/express-ai/database.json

@@ -0,0 +1 @@
+{"/":{"content":[{"type":"HeadingBlock","props":{"title":"Edit this page by adding /edit to the end of the URL","id":"HeadingBlock-1694032984497"}}],"root":{"props": {"title":""}}}}

package/dist/templates/express-ai/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "express-ai-recipe",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch --env-file-if-exists=.env.local src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@puckeditor/cloud-client": "^0",
+    "express": "^5.2.1",
+    "react": "^19.2.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.3",
+    "@types/node": "^22.10.2",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.3"
+  }
+}

package/dist/templates/express-ai/src/index.ts

@@ -0,0 +1,17 @@
+import express from "express";
+import { puckPages } from "./puck/pages.js";
+import { puckCloud } from "./puck/cloud.js";
+
+const app = express();
+app.use(express.json());
+
+app.get("/", (_req, res) => {
+  res.send("Hello Express!");
+});
+
+app.use(puckPages);
+app.use(puckCloud);
+
+app.listen(3000, () => {
+  console.log("Server is running on http://localhost:3000");
+});

package/dist/templates/express-ai/src/puck/cloud.ts

@@ -0,0 +1,71 @@
+// Handles all requests for Puck AI
+// Learn more: https://puckeditor.com/docs/ai/getting-started
+import { Readable } from "node:stream";
+import express from "express";
+import type { Request, Response } from "express";
+import type { PuckCloudOptions } from "@puckeditor/cloud-client";
+import { puckHandler } from "@puckeditor/cloud-client";
+
+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\`
+      `,
+    },
+  },
+};
+
+// puckHandler takes a web Request, so convert Express's request to one
+const toWebRequest = (req: Request) => {
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (Array.isArray(value)) value.forEach((v) => headers.append(key, v));
+    else if (value !== undefined) headers.set(key, value);
+  }
+
+  let body: BodyInit | undefined;
+  if (req.method !== "GET" && req.method !== "HEAD") {
+    if (req.readableEnded) {
+      // A body parser like express.json() already read the body
+      body = JSON.stringify(req.body ?? {});
+      headers.delete("content-length");
+    } else {
+      body = Readable.toWeb(req) as ReadableStream;
+    }
+  }
+
+  return new globalThis.Request(
+    new URL(req.originalUrl, `${req.protocol}://${req.get("host")}`),
+    { method: req.method, headers, body, duplex: "half" } as RequestInit
+  );
+};
+
+// ...and stream the web Response back through Express
+const sendWebResponse = (res: Response, response: globalThis.Response) => {
+  res.status(response.status);
+  response.headers.forEach((value, key) => res.setHeader(key, value));
+  if (!response.body) return res.end();
+  Readable.fromWeb(response.body as any).pipe(res);
+};
+
+export const puckCloud = express.Router();
+
+puckCloud.use("/api/puck", async (req, res, next) => {
+  try {
+    sendWebResponse(res, await puckHandler(toWebRequest(req), options));
+  } catch (error) {
+    next(error);
+  }
+});

package/dist/templates/express-ai/src/puck/pages.ts

@@ -0,0 +1,39 @@
+// Loads and saves Puck pages for the editor
+// Learn more: https://puckeditor.com/docs/cli
+import fs from "node:fs/promises";
+import express from "express";
+
+// Replace this with your own database
+const databasePath = "database.json";
+
+const readPages = async (): Promise<Record<string, unknown>> => {
+  try {
+    return JSON.parse(await fs.readFile(databasePath, "utf-8"));
+  } catch {
+    return {};
+  }
+};
+
+export const puckPages = express.Router();
+
+puckPages.get("/api/pages", async (req, res) => {
+  const pages = await readPages();
+  const page = pages[typeof req.query.path === "string" ? req.query.path : "/"];
+
+  if (page) res.json(page);
+  else res.status(404).json({ error: "Not found" });
+});
+
+puckPages.post(
+  "/api/pages",
+  express.json({ limit: "10mb" }),
+  async (req, res) => {
+    const { path, data } = req.body;
+    const pages = await readPages();
+
+    pages[path] = data;
+    await fs.writeFile(databasePath, JSON.stringify(pages));
+
+    res.json({ status: "ok" });
+  }
+);

package/dist/templates/express-ai/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  }
+}

package/dist/templates/hono/README.md

@@ -0,0 +1,66 @@
+# Puck + Hono recipe
+
+[Puck](https://puckeditor.com) is the open-source visual editor for React.
+
+This recipe is a [Hono](https://hono.dev) server that stores Puck pages. It has no editor of its own: point a Puck editor in your React app at it.
+
+## The APIs
+
+| Route                        | Purpose                                           |
+| ---------------------------- | ------------------------------------------------- |
+| `GET /api/pages?path=/about` | Returns the saved page data for a path, or a 404. |
+| `POST /api/pages`            | Saves `{ "path": "/about", "data": { ... } }`.    |
+
+## Run the recipe
+
+### 1. Start the server
+
+Run:
+
+```sh
+npm run dev
+```
+
+Once the server is running, [http://localhost:3000/api/pages?path=/](http://localhost:3000/api/pages?path=/) returns the home page's data.
+
+### 2. Connect an editor
+
+Load and save pages from your editor with the pages API:
+
+```tsx
+<Puck
+  config={config}
+  data={await(await fetch("/api/pages?path=/")).json()}
+  onPublish={(data) =>
+    fetch("/api/pages", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ path: "/", data }),
+    })
+  }
+/>
+```
+
+If your editor runs on another origin, proxy `/api` to this server in development (for example with Vite's [`server.proxy`](https://vite.dev/config/server-options#server-proxy)), or enable CORS.
+
+## How it works
+
+| File                | Purpose                                                                             |
+| ------------------- | ----------------------------------------------------------------------------------- |
+| `src/index.ts`      | Creates the Hono app and mounts the Puck routes with `app.route("/", puckPages);`.  |
+| `src/puck/pages.ts` | Reads and writes page data in `database.json`. Replace this with your own database. |
+| `database.json`     | Acts as a local database. Replace this with your own database solution.             |
+
+## Before deploying to production
+
+Before deploying this recipe, make sure to:
+
+- **Protect the APIs.** The pages API is public by default. Add authentication, authorization to protect page data.
+- **Use a real database.** Replace `database.json` and `src/puck/pages.ts`. Local files are not reliable across server instances or serverless deployments.
+
+## Learn more
+
+- [Puck documentation](https://puckeditor.com/docs)
+- [Integrating Puck](https://puckeditor.com/docs/integrating-puck/component-configuration)
+- [Hono](https://hono.dev)
+- [Puck Discord](https://discord.gg/D9e4E3MQVZ)