@puckeditor/cli 0.24.0-canary.301a0304

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

@@ -0,0 +1,57 @@
+/**
+ * This file implements a *magic* catch-all route that renders the Puck editor.
+ *
+ * This route exposes /puck/[...puckPath], but is disabled by middleware.ts. The middleware
+ * then rewrites all URL requests ending in `/edit` to this route, allowing you to visit any
+ * page in your application and add /edit to the end to spin up a Puck editor.
+ *
+ * This approach enables public pages to be statically rendered whilst the /puck route can
+ * remain dynamic.
+ *
+ * NB this route is public, and you will need to add authentication
+ */
+
+import "@puckeditor/core/puck.css";
+import "@puckeditor/plugin-ai/styles.css";
+import type { Data } from "@puckeditor/core";
+import { Metadata } from "next";
+import { Client } from "./client";
+import { getPage } from "../../../lib/get-page";
+
+// Empty data for new pages
+const EMPTY_PAGE_DATA: Data = {
+  content: [],
+  root: {
+    props: {
+      title: "",
+    },
+  },
+};
+
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ puckPath: string[] }>;
+}): Promise<Metadata> {
+  const { puckPath = [] } = await params;
+  const path = `/${puckPath.join("/")}`;
+
+  return {
+    title: "Puck: " + path,
+  };
+}
+
+export default async function Page({
+  params,
+}: {
+  params: Promise<{ puckPath: string[] }>;
+}) {
+  const { puckPath = [] } = await params;
+  const path = `/${puckPath.join("/")}`;
+
+  const data = getPage(path);
+
+  return <Client path={path} data={data || EMPTY_PAGE_DATA} />;
+}
+
+export const dynamic = "force-dynamic";

package/dist/templates/next-ai/app/puck/page.tsx

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

package/dist/templates/next-ai/app/styles.css

@@ -0,0 +1,3 @@
+body {
+  margin: 0;
+}

package/dist/templates/next-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/next-ai/lib/get-page.ts

@@ -0,0 +1,11 @@
+import { Data } from "@puckeditor/core";
+import fs from "fs";
+
+// Replace with a call to your database
+export const getPage = (path: string) => {
+  const allData: Record<string, Data> | null = fs.existsSync("database.json")
+    ? JSON.parse(fs.readFileSync("database.json", "utf-8"))
+    : null;
+
+  return allData ? allData[path] : null;
+};

package/dist/templates/next-ai/next.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  reactStrictMode: true,
+};

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

@@ -0,0 +1,27 @@
+{
+  "name": "next-ai-recipe",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev --turbo",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint"
+  },
+  "dependencies": {
+    "@puckeditor/cloud-client": "^0",
+    "@puckeditor/core": "workspace:*",
+    "@puckeditor/plugin-ai": "^0",
+    "classnames": "^2.3.2",
+    "next": "^16.2.11",
+    "react": "^19.2.1",
+    "react-dom": "^19.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^17.0.12",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "eslint-config-custom": "workspace:*",
+    "typescript": "^5.5.4"
+  }
+}

package/dist/templates/next-ai/proxy.ts

@@ -0,0 +1,27 @@
+import { NextResponse } from "next/server";
+
+import type { NextRequest } from "next/server";
+
+export async function proxy(req: NextRequest) {
+  const res = NextResponse.next({ request: req });
+
+  if (req.method === "GET") {
+    // Rewrite routes that match "/[...puckPath]/edit" to "/puck/[...puckPath]"
+    if (req.nextUrl.pathname.endsWith("/edit")) {
+      const pathWithoutEdit = req.nextUrl.pathname.slice(
+        0,
+        req.nextUrl.pathname.length - 5
+      );
+      const pathWithEditPrefix = `/puck${pathWithoutEdit}`;
+
+      return NextResponse.rewrite(new URL(pathWithEditPrefix, req.url));
+    }
+
+    // Disable "/puck/[...puckPath]"
+    if (req.nextUrl.pathname.startsWith("/puck")) {
+      return NextResponse.redirect(new URL("/", req.url));
+    }
+  }
+
+  return res;
+}

package/dist/templates/next-ai/puck.config.tsx

@@ -0,0 +1,25 @@
+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>
+      ),
+    },
+  },
+};
+
+export default config;

package/dist/templates/next-ai/tsconfig/base.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "Default",
+  "compilerOptions": {
+    "composite": false,
+    "declaration": true,
+    "declarationMap": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "inlineSources": false,
+    "isolatedModules": true,
+    "moduleResolution": "node",
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "preserveWatchOutput": true,
+    "skipLibCheck": true,
+    "strict": true
+  },
+  "exclude": ["node_modules"]
+}

package/dist/templates/next-ai/tsconfig/nextjs.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "Next.js",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "plugins": [{ "name": "next" }],
+    "allowJs": true,
+    "declaration": false,
+    "declarationMap": false,
+    "incremental": true,
+    "jsx": "preserve",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "module": "esnext",
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "strict": false,
+    "target": "es5"
+  },
+  "include": ["src", "next-env.d.ts"],
+  "exclude": ["node_modules"]
+}

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

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig/nextjs.json",
+  "compilerOptions": {
+    "plugins": [{ "name": "next" }]
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

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

@@ -0,0 +1,113 @@
+# Puck + React Router recipe
+
+[Puck](https://puckeditor.com) is the open-source visual editor for React.
+
+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.
+
+## 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: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
+
+Before deploying this recipe, make sure to:
+
+- **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.
+
+## 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)
+- [React Router framework mode](https://reactrouter.com/start/framework/installation)
+- [Puck Discord](https://discord.gg/D9e4E3MQVZ)

package/dist/templates/react-router/_gitignore

@@ -0,0 +1,6 @@
+.DS_Store
+/node_modules/
+
+# React Router
+/.react-router/
+/build/

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

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

package/dist/templates/react-router/app/lib/pages.server.ts

@@ -0,0 +1,29 @@
+import path from "path";
+import { fileURLToPath } from "url";
+import fs from "fs/promises";
+import type { Data } from "@puckeditor/core";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const databasePath = path.join(__dirname, "..", "..", "database.json");
+
+export async function getPage(path: string) {
+  const pages = await readDatabase();
+  return pages[path];
+}
+
+export async function savePage(path: string, data: Data) {
+  const pages = await readDatabase();
+  pages[path] = data;
+  await fs.writeFile(databasePath, JSON.stringify(pages), { encoding: "utf8" });
+}
+
+async function readDatabase() {
+  try {
+    const file = await fs.readFile(databasePath, "utf8");
+    return JSON.parse(file) as Record<string, Data>;
+  } catch (error: unknown) {
+    console.error(error);
+    return {};
+  }
+}

package/dist/templates/react-router/app/lib/resolve-puck-path.server.ts

@@ -0,0 +1,19 @@
+export function resolvePuckPath(
+  path = "",
+  // `base` can be any valid origin, it is required for the URL constructor so
+  // we can return a pathname - you can change this if you want, but it isn't
+  // important
+  base = "https://placeholder.com/"
+) {
+  const url = new URL(path, base);
+  const segments = url.pathname.split("/");
+  const isEditorRoute = segments.at(-1) === "edit";
+  const pathname = isEditorRoute
+    ? segments.slice(0, -1).join("/")
+    : url.pathname;
+
+  return {
+    isEditorRoute,
+    path: new URL(pathname, base).pathname,
+  };
+}

package/dist/templates/react-router/app/root.tsx

@@ -0,0 +1,65 @@
+import {
+  isRouteErrorResponse,
+  Links,
+  Meta,
+  Outlet,
+  Scripts,
+  ScrollRestoration,
+} from "react-router";
+
+import type { Route } from "./+types/root";
+
+export function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <Meta />
+        <Links />
+      </head>
+      <body>
+        {children}
+        <ScrollRestoration />
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+
+export default function App() {
+  return <Outlet />;
+}
+
+export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) {
+  let message = "Oops!";
+  let details = "An unexpected error occurred.";
+  let stack: string | undefined;
+
+  if (isRouteErrorResponse(error)) {
+    message = error.status === 404 ? "404" : "Error";
+    details =
+      error.status === 404
+        ? "The requested page could not be found."
+        : error.statusText || details;
+  } else if (
+    import.meta.env.NODE_ENV !== "production" &&
+    error &&
+    error instanceof Error
+  ) {
+    details = error.message;
+    stack = error.stack;
+  }
+
+  return (
+    <main>
+      <h1>{message}</h1>
+      <p>{details}</p>
+      {stack && (
+        <pre>
+          <code>{stack}</code>
+        </pre>
+      )}
+    </main>
+  );
+}

package/dist/templates/react-router/app/routes/_index.tsx

@@ -0,0 +1,31 @@
+import type { Route } from "./+types/_index";
+import { PuckRender } from "~/components/puck-render";
+import { resolvePuckPath } from "~/lib/resolve-puck-path.server";
+import { getPage } from "~/lib/pages.server";
+
+export async function loader() {
+  const { isEditorRoute, path } = resolvePuckPath("/");
+  let page = await getPage(path);
+
+  if (!page) {
+    throw new Response("Not Found", { status: 404 });
+  }
+
+  return {
+    isEditorRoute,
+    path,
+    data: page,
+  };
+}
+
+export function meta({ loaderData }: Route.MetaArgs) {
+  return [
+    {
+      title: loaderData.data.root.props?.title ?? "",
+    },
+  ];
+}
+
+export default function PuckSplatRoute({ loaderData }: Route.ComponentProps) {
+  return <PuckRender data={loaderData.data} />;
+}

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

@@ -0,0 +1,95 @@
+import { useFetcher, useLoaderData } from "react-router";
+import type { Data } from "@puckeditor/core";
+import { Puck, Render } from "@puckeditor/core";
+
+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 editorStyles from "@puckeditor/core/puck.css?url";
+
+export async function loader({ params }: Route.LoaderArgs) {
+  const pathname = params["*"] ?? "/";
+  const { isEditorRoute, path } = resolvePuckPath(pathname);
+  let page = await getPage(path);
+
+  // Throw a 404 if we're not rendering the editor and data for the page does not exist
+  if (!isEditorRoute && !page) {
+    throw new Response("Not Found", { status: 404 });
+  }
+
+  // Empty shell for new pages
+  if (isEditorRoute && !page) {
+    page = {
+      content: [],
+      root: {
+        props: {
+          title: "",
+        },
+      },
+    };
+  }
+
+  return {
+    isEditorRoute,
+    path,
+    data: page,
+  };
+}
+
+export function meta({ loaderData }: Route.MetaArgs) {
+  return [
+    {
+      title: loaderData.isEditorRoute
+        ? `Edit: ${loaderData.path}`
+        : loaderData.data.root.props?.title ?? "",
+    },
+  ];
+}
+
+export async function action({ params, request }: Route.ActionArgs) {
+  const pathname = params["*"] ?? "/";
+  const { path } = resolvePuckPath(pathname);
+  const body = (await request.json()) as { data: Data };
+
+  await savePage(path, body.data);
+}
+
+function Editor() {
+  const loaderData = useLoaderData<typeof loader>();
+  const fetcher = useFetcher<typeof action>();
+
+  return (
+    <>
+      <link rel="stylesheet" href={editorStyles} id="puck-css" />
+      <Puck
+        config={config}
+        data={loaderData.data}
+        onPublish={async (data) => {
+          await fetcher.submit(
+            {
+              data,
+            },
+            {
+              action: "",
+              method: "post",
+              encType: "application/json",
+            }
+          );
+        }}
+      />
+    </>
+  );
+}
+
+export default function PuckSplatRoute({ loaderData }: Route.ComponentProps) {
+  return (
+    <div>
+      {loaderData.isEditorRoute ? (
+        <Editor />
+      ) : (
+        <Render config={config} data={loaderData.data} />
+      )}
+    </div>
+  );
+}

package/dist/templates/react-router/app/routes.ts

@@ -0,0 +1,7 @@
+import type { RouteConfig } from "@react-router/dev/routes";
+import { route, index } from "@react-router/dev/routes";
+
+export default [
+  index("routes/_index.tsx"),
+  route("*", "routes/puck-splat.tsx"),
+] satisfies RouteConfig;

package/dist/templates/react-router/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":"Puck + React Router 7 demo"}},"zones":{}}}

package/dist/templates/react-router/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "react-router-recipe",
+  "private": true,
+  "type": "module",
+  "version": "1.0.0",
+  "scripts": {
+    "build": "react-router build",
+    "dev": "react-router dev",
+    "start": "react-router-serve ./build/server/index.js",
+    "typecheck": "react-router typegen && tsc"
+  },
+  "dependencies": {
+    "@puckeditor/core": "workspace:*",
+    "@react-router/node": "^7.18.0",
+    "@react-router/serve": "^7.18.0",
+    "isbot": "^5",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-router": "^7.18.0"
+  },
+  "devDependencies": {
+    "@react-router/dev": "^7.18.0",
+    "@types/node": "^20",
+    "@types/react": "^19.0.1",
+    "@types/react-dom": "^19.0.2",
+    "typescript": "^5.8.3",
+    "vite": "^7.3.2",
+    "vite-tsconfig-paths": "^5.1.4"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/dist/templates/react-router/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>
+      ),
+    },
+  },
+};