@puckeditor/cli 0.24.0-canary.301a0304

package/dist/templates/react-router/react-router.config.ts

@@ -0,0 +1,7 @@
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  // Config options...
+  // Server-side render by default, to enable SPA mode set this to `false`
+  ssr: true,
+} satisfies Config;

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

@@ -0,0 +1,29 @@
+{
+  "include": [
+    "**/*",
+    "**/.server/**/*",
+    "**/.client/**/*",
+    ".react-router/types/**/*"
+  ],
+  "compilerOptions": {
+    "lib": ["DOM", "DOM.Iterable", "ES2022"],
+    "types": ["node", "vite/client"],
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "rootDirs": [".", "./.react-router/types"],
+    "baseUrl": ".",
+    "paths": {
+      "~/*": ["./app/*"],
+      "@puckeditor/core": ["../../packages/core/index.ts"],
+      "@puckeditor/core/puck.css": ["../../packages/core/bundle/index.css"]
+    },
+    "esModuleInterop": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "strict": true
+  }
+}

package/dist/templates/react-router/vite.config.ts

@@ -0,0 +1,10 @@
+import { reactRouter } from "@react-router/dev/vite";
+import { defineConfig } from "vite";
+import tsconfigPaths from "vite-tsconfig-paths";
+
+export default defineConfig({
+  plugins: [reactRouter(), tsconfigPaths()],
+  optimizeDeps: {
+    include: ["@puckeditor/core"],
+  },
+});

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

@@ -0,0 +1,172 @@
+# Puck AI + React Router recipe
+
+[Puck](https://puckeditor.com) is the open-source visual editor for React. It lets you create page builders that use your own components.
+
+[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.
+
+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.
+
+## 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
+/>
+```
+
+### 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} />;
+}
+```
+
+#### The Cloud Client
+
+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.
+
+```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
+```
+
+### 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
+
+Before deploying this recipe, make sure to:
+
+- **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.
+
+## 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 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/dist/templates/react-router-ai/_gitignore

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

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

@@ -0,0 +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 }) {
+  const configWithDesignedComponents = withDynamicConfig(config, data);
+
+  return <Render config={configWithDesignedComponents} data={data} />;
+}

package/dist/templates/react-router-ai/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-ai/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-ai/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-ai/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-ai/app/routes/api.puck.ts

@@ -0,0 +1,34 @@
+// Handles all requests for Puck AI
+// Learn more: https://puckeditor.com/docs/ai/getting-started
+import type { ActionFunctionArgs, LoaderFunctionArgs } from "react-router";
+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 async function loader(args: LoaderFunctionArgs) {
+  return puckHandler(args.request, options);
+}
+
+export async function action(args: ActionFunctionArgs) {
+  return puckHandler(args.request, options);
+}

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

@@ -0,0 +1,119 @@
+import { useMemo } from "react";
+import { useFetcher, useLoaderData } from "react-router";
+import type { Data } from "@puckeditor/core";
+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 type { UserData } 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";
+
+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);
+}
+
+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={plugins}
+        config={configWithDesignedComponents}
+        data={loaderData.data}
+        onPublish={async (data) => {
+          await fetcher.submit(
+            { data: data as UserData },
+            {
+              action: "",
+              method: "post",
+              encType: "application/json",
+            }
+          );
+        }}
+      />
+    </>
+  );
+}
+
+export default function PuckSplatRoute({ loaderData }: Route.ComponentProps) {
+  return (
+    <div>
+      {loaderData.isEditorRoute ? (
+        <Editor />
+      ) : (
+        <PuckRender data={loaderData.data} />
+      )}
+    </div>
+  );
+}

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

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

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

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

@@ -0,0 +1,35 @@
+{
+  "name": "react-router-ai-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/cloud-client": "^0",
+    "@puckeditor/core": "workspace:*",
+    "@puckeditor/plugin-ai": "^0",
+    "@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-ai/puck.config.tsx

@@ -0,0 +1,25 @@
+import type { Config, Data } from "@puckeditor/core";
+
+export type Props = {
+  HeadingBlock: { title: string };
+};
+
+export type UserData = Data<Props>;
+
+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/react-router-ai/react-router.config.ts

@@ -0,0 +1,7 @@
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  // Config options...
+  // Server-side render by default, to enable SPA mode set this to `false`
+  ssr: true,
+} satisfies Config;

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

@@ -0,0 +1,29 @@
+{
+  "include": [
+    "**/*",
+    "**/.server/**/*",
+    "**/.client/**/*",
+    ".react-router/types/**/*"
+  ],
+  "compilerOptions": {
+    "lib": ["DOM", "DOM.Iterable", "ES2022"],
+    "types": ["node", "vite/client"],
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "rootDirs": [".", "./.react-router/types"],
+    "baseUrl": ".",
+    "paths": {
+      "~/*": ["./app/*"],
+      "@puckeditor/core": ["../../packages/core/index.ts"],
+      "@puckeditor/core/puck.css": ["../../packages/core/bundle/index.css"]
+    },
+    "esModuleInterop": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "strict": true
+  }
+}

package/dist/templates/react-router-ai/vite.config.ts

@@ -0,0 +1,10 @@
+import { reactRouter } from "@react-router/dev/vite";
+import { defineConfig } from "vite";
+import tsconfigPaths from "vite-tsconfig-paths";
+
+export default defineConfig({
+  plugins: [reactRouter(), tsconfigPaths()],
+  optimizeDeps: {
+    include: ["@puckeditor/core", "@puckeditor/plugin-ai"],
+  },
+});