@puckeditor/cli 0.24.0-canary.301a0304

package/dist/templates/hono/_gitignore

@@ -0,0 +1,32 @@
+# dev
+.yarn/
+!.yarn/releases
+.vscode/*
+!.vscode/launch.json
+!.vscode/*.code-snippets
+.idea/workspace.xml
+.idea/usage.statistics.xml
+.idea/shelf
+
+# deps
+node_modules/
+
+# env
+.env
+.env.local
+.env.production
+
+# build
+dist/
+
+# logs
+logs/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+# misc
+.DS_Store

package/dist/templates/hono/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/hono/package.json

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

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

@@ -0,0 +1,21 @@
+import { serve } from "@hono/node-server";
+import { Hono } from "hono";
+import { puckPages } from "./puck/pages.js";
+
+const app = new Hono();
+
+app.get("/", (c) => {
+  return c.text("Hello Hono!");
+});
+
+app.route("/", puckPages);
+
+serve(
+  {
+    fetch: app.fetch,
+    port: 3000,
+  },
+  (info) => {
+    console.log(`Server is running on http://localhost:${info.port}`);
+  }
+);

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

@@ -0,0 +1,32 @@
+// Loads and saves Puck pages for the editor
+// Learn more: https://puckeditor.com/docs/cli
+import fs from "node:fs/promises";
+import { Hono } from "hono";
+
+// 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 = new Hono()
+  .get("/api/pages", async (c) => {
+    const pages = await readPages();
+    const page = pages[c.req.query("path") ?? "/"];
+
+    return page ? c.json(page) : c.json({ error: "Not found" }, 404);
+  })
+  .post("/api/pages", async (c) => {
+    const { path, data } = await c.req.json();
+    const pages = await readPages();
+
+    pages[path] = data;
+    await fs.writeFile(databasePath, JSON.stringify(pages));
+
+    return c.json({ status: "ok" });
+  });

package/dist/templates/hono/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "NodeNext",
+    "strict": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "exclude": ["node_modules"]
+}

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

@@ -0,0 +1,81 @@
+# Puck AI + 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 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 Hono app and mounts the Puck routes with `app.route("/", puckPages);` and `app.route("/", 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)
+- [Hono](https://hono.dev)
+- [Puck Discord](https://discord.gg/D9e4E3MQVZ)

package/dist/templates/hono-ai/_gitignore

@@ -0,0 +1,32 @@
+# dev
+.yarn/
+!.yarn/releases
+.vscode/*
+!.vscode/launch.json
+!.vscode/*.code-snippets
+.idea/workspace.xml
+.idea/usage.statistics.xml
+.idea/shelf
+
+# deps
+node_modules/
+
+# env
+.env
+.env.local
+.env.production
+
+# build
+dist/
+
+# logs
+logs/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+# misc
+.DS_Store

package/dist/templates/hono-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/hono-ai/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "hono-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": {
+    "@hono/node-server": "^2.1.1",
+    "@puckeditor/cloud-client": "^0",
+    "hono": "^4.13.9",
+    "react": "^19.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.3"
+  }
+}

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

@@ -0,0 +1,23 @@
+import { serve } from "@hono/node-server";
+import { Hono } from "hono";
+import { puckPages } from "./puck/pages.js";
+import { puckCloud } from "./puck/cloud.js";
+
+const app = new Hono();
+
+app.get("/", (c) => {
+  return c.text("Hello Hono!");
+});
+
+app.route("/", puckPages);
+app.route("/", puckCloud);
+
+serve(
+  {
+    fetch: app.fetch,
+    port: 3000,
+  },
+  (info) => {
+    console.log(`Server is running on http://localhost:${info.port}`);
+  }
+);

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

@@ -0,0 +1,30 @@
+// Handles all requests for Puck AI
+// Learn more: https://puckeditor.com/docs/ai/getting-started
+import { Hono } from "hono";
+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\`
+      `,
+    },
+  },
+};
+
+export const puckCloud = new Hono().all("/api/puck/*", (c) =>
+  puckHandler(c.req.raw, options)
+);

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

@@ -0,0 +1,32 @@
+// Loads and saves Puck pages for the editor
+// Learn more: https://puckeditor.com/docs/cli
+import fs from "node:fs/promises";
+import { Hono } from "hono";
+
+// 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 = new Hono()
+  .get("/api/pages", async (c) => {
+    const pages = await readPages();
+    const page = pages[c.req.query("path") ?? "/"];
+
+    return page ? c.json(page) : c.json({ error: "Not found" }, 404);
+  })
+  .post("/api/pages", async (c) => {
+    const { path, data } = await c.req.json();
+    const pages = await readPages();
+
+    pages[path] = data;
+    await fs.writeFile(databasePath, JSON.stringify(pages));
+
+    return c.json({ status: "ok" });
+  });

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

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "NodeNext",
+    "strict": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "exclude": ["node_modules"]
+}

package/dist/templates/manifest.json

@@ -0,0 +1,4 @@
+{
+  "cloudClientRange": "^0",
+  "pluginAiRange": "^0"
+}

package/dist/templates/next/README.md

@@ -0,0 +1,112 @@
+# Puck + Next.js recipe
+
+[Puck](https://puckeditor.com) is the open-source visual editor for React.
+
+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.
+
+## Core concepts
+
+If you're new to Puck, this section introduces the core concepts you need to know.
+
+### 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>,
+    },
+  },
+};
+```
+
+#### 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
+  }}
+/>
+```
+
+#### 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
+/>
+```
+
+## Run the recipe
+
+### 1. 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.
+
+### 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.                            |
+
+## Before deploying to production
+
+Before deploying this recipe, make sure 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.
+
+## Learn more
+
+- [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/dist/templates/next/_gitignore

@@ -0,0 +1,35 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+next-env.d.ts
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# vercel
+.vercel

package/dist/templates/next/app/[...puckPath]/client.tsx

@@ -0,0 +1,9 @@
+"use client";
+
+import type { Data } from "@puckeditor/core";
+import { Render } from "@puckeditor/core";
+import config from "../../puck.config";
+
+export function Client({ data }: { data: Data }) {
+  return <Render config={config} data={data} />;
+}

package/dist/templates/next/app/[...puckPath]/page.tsx

@@ -0,0 +1,49 @@
+/**
+ * This file implements a catch-all route that renders the user-facing pages
+ * generated by Puck. For any route visited (with exception of other hardcoded
+ * pages in /app), it will check your database (via `getPage`) for a Puck page
+ * and render it using <Render>.
+ *
+ * All routes produced by this page are statically rendered using incremental
+ * static site generation. After the first visit, the page will be cached as
+ * a static file. Subsequent visits will receive the cache. Publishing a page
+ * will invalidate the cache as the page is written in /api/puck/route.ts
+ */
+
+import { Client } from "./client";
+import { notFound } from "next/navigation";
+import { Metadata } from "next";
+import { getPage } from "../../lib/get-page";
+
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ puckPath: string[] }>;
+}): Promise<Metadata> {
+  const { puckPath = [] } = await params;
+  const path = `/${puckPath.join("/")}`;
+
+  return {
+    title: getPage(path)?.root.props?.title,
+  };
+}
+
+export default async function Page({
+  params,
+}: {
+  params: Promise<{ puckPath: string[] }>;
+}) {
+  const { puckPath = [] } = await params;
+  const path = `/${puckPath.join("/")}`;
+  const data = getPage(path);
+
+  if (!data) {
+    return notFound();
+  }
+
+  return <Client data={data} />;
+}
+
+// Force Next.js to produce static pages: https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config#dynamic
+// Delete this if you need dynamic rendering, such as access to headers or cookies
+export const dynamic = "force-static";

package/dist/templates/next/app/layout.tsx

@@ -0,0 +1,13 @@
+import "./styles.css";
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}

package/dist/templates/next/app/page.tsx

@@ -0,0 +1 @@
+export { default, generateMetadata } from "./[...puckPath]/page";

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

@@ -0,0 +1,20 @@
+"use client";
+
+import type { Data } from "@puckeditor/core";
+import { Puck } from "@puckeditor/core";
+import config from "../../../puck.config";
+
+export function Client({ path, data }: { path: string; data: Data }) {
+  return (
+    <Puck
+      config={config}
+      data={data}
+      onPublish={async (data) => {
+        await fetch("/puck/api", {
+          method: "post",
+          body: JSON.stringify({ data, path }),
+        });
+      }}
+    />
+  );
+}