@puckeditor/cli 0.24.0-canary.301a0304

package/dist/templates/vite/src/puck/editor.tsx

@@ -0,0 +1,28 @@
+import { useEffect, useState } from "react";
+import type { Data } from "@puckeditor/core";
+import { Puck } from "@puckeditor/core";
+import "@puckeditor/core/puck.css";
+
+import { config } from "../puck.config";
+import { loadPage, savePage } from "./pages";
+
+// Empty shell for new pages
+const emptyPage: Data = { content: [], root: { props: { title: "" } } };
+
+export default function Editor({ path }: { path: string }) {
+  const [data, setData] = useState<Data | null>(null);
+
+  useEffect(() => {
+    loadPage(path).then((page) => setData(page ?? emptyPage));
+  }, [path]);
+
+  if (!data) return null;
+
+  return (
+    <Puck
+      config={config}
+      data={data}
+      onPublish={(data) => savePage(path, data)}
+    />
+  );
+}

package/dist/templates/vite/src/puck/page.tsx

@@ -0,0 +1,27 @@
+import { useEffect, useState } from "react";
+import type { ReactNode } from "react";
+import type { Data } from "@puckeditor/core";
+import { Render } from "@puckeditor/core";
+
+import { config } from "../puck.config";
+import { loadPage } from "./pages";
+
+/** Renders the published Puck page for a path, or `fallback` if there isn't one */
+export function PuckPage({
+  path,
+  fallback = null,
+}: {
+  path: string;
+  fallback?: ReactNode;
+}) {
+  const [data, setData] = useState<Data | null>();
+
+  useEffect(() => {
+    loadPage(path).then(setData);
+  }, [path]);
+
+  if (data === undefined) return null;
+  if (data === null) return fallback;
+
+  return <Render config={config} data={data} />;
+}

package/dist/templates/vite/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/vite/src/puck/root.tsx

@@ -0,0 +1,27 @@
+import { lazy, Suspense } from "react";
+import type { ReactNode } from "react";
+
+// Loaded only when editing, so the editor stays out of your app's bundle
+const Editor = lazy(() => import("./editor"));
+
+/** The path being edited for URLs ending in /edit, e.g. /about/edit */
+export const editorPath = (pathname: string) => {
+  const segments = pathname.split("/");
+  if (segments.at(-1) !== "edit") return null;
+  return segments.slice(0, -1).join("/") || "/";
+};
+
+/** Renders the Puck editor at /edit URLs, and your app everywhere else */
+export function PuckRoot({ children }: { children: ReactNode }) {
+  const path = editorPath(window.location.pathname);
+  if (path === null) return children;
+
+  return (
+    // Fill the window, whatever layout styles your app gives its root
+    <div style={{ position: "fixed", inset: 0, textAlign: "initial" }}>
+      <Suspense>
+        <Editor path={path} />
+      </Suspense>
+    </div>
+  );
+}

package/dist/templates/vite/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/vite/tsconfig.app.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023", "DOM"],
+    "module": "esnext",
+    "types": ["vite/client"],
+    "allowArbitraryExtensions": true,
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"]
+}

package/dist/templates/vite/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
+}

package/dist/templates/vite/tsconfig.node.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023"],
+    "types": ["node"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "module": "nodenext",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["vite.config.ts", "server"]
+}

package/dist/templates/vite/vite.config.ts

@@ -0,0 +1,14 @@
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+import devServer from "@hono/vite-dev-server";
+
+// https://vite.dev/config/
+export default defineConfig({
+  plugins: [
+    react(),
+    devServer({ entry: "server/index.ts", exclude: [/^(?!\/api\/).*/] }),
+  ],
+  optimizeDeps: {
+    include: ["@puckeditor/core"],
+  },
+});

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

@@ -0,0 +1,67 @@
+# Puck AI + Vite recipe
+
+[Puck](https://puckeditor.com) is the open-source visual editor for React.
+
+This recipe adds Puck and Puck AI to a [Vite](https://vite.dev) React app. A small [Hono](https://hono.dev) server in `server/` stores pages and serves Puck AI. Vite runs it in development with [`@hono/vite-dev-server`](https://github.com/honojs/vite-plugins/tree/main/packages/dev-server), and `npm start` serves it with the built app in production.
+
+## 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 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. Publish a page
+
+Click the **AI** button in the left sidebar, enter a prompt, and press Enter. Once your page is ready, select **Publish** in the header to save it, then navigate to [http://localhost:5173](http://localhost:5173) to view it.
+
+You can also create a page at any path by navigating to `/your/path/edit` and publishing it.
+
+## How it works
+
+`PuckRoot` (`src/puck/root.tsx`) wraps the app in `src/main.tsx`. When a URL ends in `/edit`, it renders the editor for that path instead of the app. The editor is loaded on demand, so it stays out of the app's bundle.
+
+Selecting **Publish** sends the page to `POST /api/pages`, which writes it to `database.json`. `<PuckPage>` (`src/puck/page.tsx`) loads a published page from `GET /api/pages` and renders it with [`<Render>`](https://puckeditor.com/docs/api-reference/components/render). Put it wherever your app renders pages; this recipe's `App` renders it for every URL.
+
+| File                   | Purpose                                                                                            |
+| ---------------------- | -------------------------------------------------------------------------------------------------- |
+| `src/puck.config.tsx`  | Defines the components, fields, and default props available to Puck. Add your own components here. |
+| `src/puck/root.tsx`    | Renders the editor at `/edit` URLs, and your app everywhere else.                                  |
+| `src/puck/editor.tsx`  | Loads the page being edited and publishes changes.                                                 |
+| `src/puck/page.tsx`    | Loads and renders a published page.                                                                |
+| `src/puck/pages.ts`    | Calls the pages API.                                                                               |
+| `server/index.ts`      | The Hono app serving Puck's APIs.                                                                  |
+| `server/puck/pages.ts` | Reads and writes page data in `database.json`. Replace this with your own database.                |
+| `server/puck/cloud.ts` | Handles requests from the AI plugin and configures AI generation.                                  |
+| `server/prod.ts`       | Serves the built app and the APIs in production.                                                   |
+| `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 APIs.** The `/edit` routes and `/api/pages` and `/api/puck` routes are public by default. Add authentication, authorization, and rate limits.
+- **Add your component library.** Replace the example `HeadingBlock` in `src/puck.config.tsx` with the components and fields your users need.
+- **Set your business context.** Replace the example Google context in `server/puck/cloud.ts` with clear information about your product, audience, and content rules.
+- **Use a real database.** Replace `database.json` and `server/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)
+- [Vite](https://vite.dev)
+- [Puck Discord](https://discord.gg/D9e4E3MQVZ)

package/dist/templates/vite-ai/_gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

package/dist/templates/vite-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/vite-ai/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Puck + Vite</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

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

@@ -0,0 +1,31 @@
+{
+  "name": "vite-ai-recipe",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview",
+    "start": "tsx server/prod.ts"
+  },
+  "dependencies": {
+    "@hono/node-server": "^2.1.1",
+    "@puckeditor/cloud-client": "^0",
+    "@puckeditor/core": "workspace:*",
+    "@puckeditor/plugin-ai": "^0",
+    "hono": "^4.13.9",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@hono/vite-dev-server": "^0.26.1",
+    "@types/node": "^22.10.2",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitejs/plugin-react": "^6.0.1",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.0"
+  }
+}

package/dist/templates/vite-ai/server/index.ts

@@ -0,0 +1,15 @@
+// Puck's APIs, served by Vite in development and by server/prod.ts in production
+import fs from "node:fs";
+import { Hono } from "hono";
+import { puckPages } from "./puck/pages.js";
+import { puckCloud } from "./puck/cloud.js";
+
+// Vite doesn't give server code .env.local, which holds PUCK_API_KEY
+if (fs.existsSync(".env.local")) process.loadEnvFile(".env.local");
+
+const app = new Hono();
+
+app.route("/", puckPages);
+app.route("/", puckCloud);
+
+export default app;

package/dist/templates/vite-ai/server/prod.ts

@@ -0,0 +1,18 @@
+// Serves the built app and Puck's APIs in production
+import { serve } from "@hono/node-server";
+import { serveStatic } from "@hono/node-server/serve-static";
+import { Hono } from "hono";
+import api from "./index.js";
+
+const app = new Hono();
+
+app.route("/", api);
+app.use("/*", serveStatic({ root: "./dist" }));
+// Every other path loads the app, which decides what to render
+app.get("*", serveStatic({ path: "./dist/index.html" }));
+
+const port = Number(process.env.PORT ?? 3000);
+
+serve({ fetch: app.fetch, port }, () => {
+  console.log(`Server is running on http://localhost:${port}`);
+});

package/dist/templates/vite-ai/server/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/vite-ai/server/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/vite-ai/src/App.tsx

@@ -0,0 +1,11 @@
+import { PuckPage } from "./puck/page";
+
+// Renders the Puck page published at this URL
+export default function App() {
+  return (
+    <PuckPage
+      path={window.location.pathname}
+      fallback={<h1>Page not found</h1>}
+    />
+  );
+}

package/dist/templates/vite-ai/src/main.tsx

@@ -0,0 +1,12 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import App from "./App.tsx";
+import { PuckRoot } from "./puck/root";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <PuckRoot>
+      <App />
+    </PuckRoot>
+  </StrictMode>
+);

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

@@ -0,0 +1,49 @@
+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: "" } } };
+
+export default function Editor({ path }: { 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/vite-ai/src/puck/page.tsx

@@ -0,0 +1,28 @@
+import { useEffect, useState } from "react";
+import type { ReactNode } from "react";
+import type { Data } from "@puckeditor/core";
+import { Render } from "@puckeditor/core";
+import { withDynamicConfig } from "@puckeditor/plugin-ai";
+
+import { config } from "../puck.config";
+import { loadPage } from "./pages";
+
+/** Renders the published Puck page for a path, or `fallback` if there isn't one */
+export function PuckPage({
+  path,
+  fallback = null,
+}: {
+  path: string;
+  fallback?: ReactNode;
+}) {
+  const [data, setData] = useState<Data | null>();
+
+  useEffect(() => {
+    loadPage(path).then(setData);
+  }, [path]);
+
+  if (data === undefined) return null;
+  if (data === null) return fallback;
+
+  return <Render config={withDynamicConfig(config, data)} data={data} />;
+}

package/dist/templates/vite-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/vite-ai/src/puck/root.tsx

@@ -0,0 +1,27 @@
+import { lazy, Suspense } from "react";
+import type { ReactNode } from "react";
+
+// Loaded only when editing, so the editor stays out of your app's bundle
+const Editor = lazy(() => import("./editor"));
+
+/** The path being edited for URLs ending in /edit, e.g. /about/edit */
+export const editorPath = (pathname: string) => {
+  const segments = pathname.split("/");
+  if (segments.at(-1) !== "edit") return null;
+  return segments.slice(0, -1).join("/") || "/";
+};
+
+/** Renders the Puck editor at /edit URLs, and your app everywhere else */
+export function PuckRoot({ children }: { children: ReactNode }) {
+  const path = editorPath(window.location.pathname);
+  if (path === null) return children;
+
+  return (
+    // Fill the window, whatever layout styles your app gives its root
+    <div style={{ position: "fixed", inset: 0, textAlign: "initial" }}>
+      <Suspense>
+        <Editor path={path} />
+      </Suspense>
+    </div>
+  );
+}

package/dist/templates/vite-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/vite-ai/tsconfig.app.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023", "DOM"],
+    "module": "esnext",
+    "types": ["vite/client"],
+    "allowArbitraryExtensions": true,
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"]
+}

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

@@ -0,0 +1,7 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
+}