@puckeditor/cli 0.24.0-canary.301a0304

package/dist/templates/tanstack-start-ai/README.md

@@ -0,0 +1,171 @@
+# Puck AI + TanStack Start 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 [TanStack Start](https://tanstack.com/start), 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.",
+  },
+};
+
+const handleRequest = ({ request }: { request: Request }) =>
+  puckHandler(request, options);
+
+export const Route = createFileRoute("/api/puck/$")({
+  server: { handlers: { GET: handleRequest, POST: handleRequest } },
+});
+```
+
+#### 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:3000](http://localhost:3000) to view the home page, or [http://localhost:3000/edit](http://localhost:3000/edit) to edit it with Puck.
+
+### 3. Create a page with Puck AI
+
+Navigate to [http://localhost:3000/edit](http://localhost:3000/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: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`, `resolvePuckPath` (`src/lib/resolve-puck-path.ts`) returns the path of the page being edited. The loader in `src/routes/$.tsx` calls the `loadPuckPage` server function, which loads the saved page, or starts with an empty page if the path is new.
+
+Selecting **Publish** calls the `publishPuckPage` server function (`src/lib/pages.ts`), which 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. |
+| `src/routes/$.tsx`               | Loads page data, then renders the editor or published page.                                                          |
+| `src/routes/index.tsx`           | Loads and renders the home page.                                                                                     |
+| `src/routes/api/puck/$.ts`       | Handles requests from the AI plugin and configures AI generation.                                                    |
+| `src/lib/pages.ts`               | Server functions that load and publish pages.                                                                        |
+| `src/lib/resolve-puck-path.ts`   | Maps an `/edit` URL to the path of the page being edited.                                                            |
+| `src/lib/pages.server.ts`        | Reads and writes page data in `database.json`. Replace this with your own data fetching and saving logic.            |
+| `src/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, `publishPuckPage` server function, 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 `src/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 `src/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 server functions. Deploy it with one of [TanStack Start's hosting options](https://tanstack.com/start/latest/docs/framework/react/guide/hosting).
+
+## 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)
+- [TanStack Start](https://tanstack.com/start/latest/docs/framework/react/overview)
+- [Puck Discord](https://discord.gg/D9e4E3MQVZ)

package/dist/templates/tanstack-start-ai/_gitignore

@@ -0,0 +1,12 @@
+node_modules
+.DS_Store
+dist
+dist-ssr
+*.local
+.env
+.nitro
+.tanstack
+.wrangler
+.output
+.vinxi
+__unconfig*

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

@@ -0,0 +1,28 @@
+{
+  "name": "tanstack-start-ai-recipe",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev --port 3000",
+    "build": "vite build",
+    "start": "vite preview --port 3000"
+  },
+  "dependencies": {
+    "@puckeditor/cloud-client": "^0",
+    "@puckeditor/core": "workspace:*",
+    "@puckeditor/plugin-ai": "^0",
+    "@tanstack/react-router": "^1.168.0",
+    "@tanstack/react-start": "^1.168.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitejs/plugin-react": "^6.0.1",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.0"
+  }
+}

package/dist/templates/tanstack-start-ai/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/tanstack-start-ai/src/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/tanstack-start-ai/src/lib/pages.server.ts

@@ -0,0 +1,26 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import type { Data } from "@puckeditor/core";
+
+const databasePath = path.join(process.cwd(), "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/tanstack-start-ai/src/lib/pages.ts

@@ -0,0 +1,39 @@
+import { createServerFn } from "@tanstack/react-start";
+import { notFound } from "@tanstack/react-router";
+import type { Data } from "@puckeditor/core";
+
+import { getPage, savePage } from "./pages.server";
+import { resolvePuckPath } from "./resolve-puck-path";
+
+// Loads the page for a URL, or an empty page when editing a new path
+export const loadPuckPage = createServerFn({ method: "GET" })
+  .validator((pathname: string) => pathname)
+  .handler(async ({ data: pathname }) => {
+    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 notFound();
+    }
+
+    // Empty shell for new pages
+    if (isEditorRoute && !page) {
+      page = {
+        content: [],
+        root: {
+          props: {
+            title: "",
+          },
+        },
+      };
+    }
+
+    return { isEditorRoute, path, data: page as Data };
+  });
+
+export const publishPuckPage = createServerFn({ method: "POST" })
+  .validator((input: { path: string; data: Data }) => input)
+  .handler(async ({ data }) => {
+    await savePage(data.path, data.data);
+  });

package/dist/templates/tanstack-start-ai/src/lib/resolve-puck-path.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/tanstack-start-ai/src/routeTree.gen.ts

@@ -0,0 +1,104 @@
+/* eslint-disable */
+
+// @ts-nocheck
+
+// noinspection JSUnusedGlobalSymbols
+
+// This file was automatically generated by TanStack Router.
+// You should NOT make any changes in this file as it will be overwritten.
+// Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
+
+import { Route as rootRouteImport } from './routes/__root'
+import { Route as IndexRouteImport } from './routes/index'
+import { Route as SplatRouteImport } from './routes/$'
+import { Route as ApiPuckSplatRouteImport } from './routes/api/puck/$'
+
+const IndexRoute = IndexRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const SplatRoute = SplatRouteImport.update({
+  id: '/$',
+  path: '/$',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiPuckSplatRoute = ApiPuckSplatRouteImport.update({
+  id: '/api/puck/$',
+  path: '/api/puck/$',
+  getParentRoute: () => rootRouteImport,
+} as any)
+
+export interface FileRoutesByFullPath {
+  '/': typeof IndexRoute
+  '/$': typeof SplatRoute
+  '/api/puck/$': typeof ApiPuckSplatRoute
+}
+export interface FileRoutesByTo {
+  '/': typeof IndexRoute
+  '/$': typeof SplatRoute
+  '/api/puck/$': typeof ApiPuckSplatRoute
+}
+export interface FileRoutesById {
+  __root__: typeof rootRouteImport
+  '/': typeof IndexRoute
+  '/$': typeof SplatRoute
+  '/api/puck/$': typeof ApiPuckSplatRoute
+}
+export interface FileRouteTypes {
+  fileRoutesByFullPath: FileRoutesByFullPath
+  fullPaths: '/' | '/$' | '/api/puck/$'
+  fileRoutesByTo: FileRoutesByTo
+  to: '/' | '/$' | '/api/puck/$'
+  id: '__root__' | '/' | '/$' | '/api/puck/$'
+  fileRoutesById: FileRoutesById
+}
+export interface RootRouteChildren {
+  IndexRoute: typeof IndexRoute
+  SplatRoute: typeof SplatRoute
+  ApiPuckSplatRoute: typeof ApiPuckSplatRoute
+}
+
+declare module '@tanstack/react-router' {
+  interface FileRoutesByPath {
+    '/': {
+      id: '/'
+      path: '/'
+      fullPath: '/'
+      preLoaderRoute: typeof IndexRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/$': {
+      id: '/$'
+      path: '/$'
+      fullPath: '/$'
+      preLoaderRoute: typeof SplatRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/api/puck/$': {
+      id: '/api/puck/$'
+      path: '/api/puck/$'
+      fullPath: '/api/puck/$'
+      preLoaderRoute: typeof ApiPuckSplatRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+  }
+}
+
+const rootRouteChildren: RootRouteChildren = {
+  IndexRoute: IndexRoute,
+  SplatRoute: SplatRoute,
+  ApiPuckSplatRoute: ApiPuckSplatRoute,
+}
+export const routeTree = rootRouteImport
+  ._addFileChildren(rootRouteChildren)
+  ._addFileTypes<FileRouteTypes>()
+
+import type { getRouter } from './router.tsx'
+import type { createStart } from '@tanstack/react-start'
+declare module '@tanstack/react-start' {
+  interface Register {
+    ssr: true
+    router: Awaited<ReturnType<typeof getRouter>>
+  }
+}

package/dist/templates/tanstack-start-ai/src/router.tsx

@@ -0,0 +1,19 @@
+import { createRouter as createTanStackRouter } from "@tanstack/react-router";
+import { routeTree } from "./routeTree.gen";
+
+export function getRouter() {
+  const router = createTanStackRouter({
+    routeTree,
+    scrollRestoration: true,
+    defaultPreload: "intent",
+    defaultPreloadStaleTime: 0,
+  });
+
+  return router;
+}
+
+declare module "@tanstack/react-router" {
+  interface Register {
+    router: ReturnType<typeof getRouter>;
+  }
+}

package/dist/templates/tanstack-start-ai/src/routes/$.tsx

@@ -0,0 +1,73 @@
+import { useMemo } from "react";
+import { createFileRoute } from "@tanstack/react-router";
+import type { Data } from "@puckeditor/core";
+import { Puck, blocksPlugin, outlinePlugin } from "@puckeditor/core";
+import { createAiPlugin, withDynamicConfig } from "@puckeditor/plugin-ai";
+
+import { config } from "../../puck.config";
+import { loadPuckPage, publishPuckPage } from "../lib/pages";
+import { PuckRender } from "../components/puck-render";
+
+import editorStyles from "@puckeditor/core/puck.css?url";
+import pluginStyles from "@puckeditor/plugin-ai/styles.css?url";
+
+export const Route = createFileRoute("/$")({
+  loader: ({ params }) => loadPuckPage({ data: params._splat ?? "" }),
+  head: ({ loaderData }) => ({
+    meta: [
+      {
+        title: loaderData?.isEditorRoute
+          ? `Edit: ${loaderData.path}`
+          : loaderData?.data.root.props?.title ?? "",
+      },
+    ],
+    links: loaderData?.isEditorRoute
+      ? [
+          { rel: "stylesheet", href: editorStyles },
+          { rel: "stylesheet", href: pluginStyles },
+        ]
+      : [],
+  }),
+  component: PuckSplatRoute,
+});
+
+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({ path, data }: { path: string; data: Data }) {
+  const configWithDesignedComponents = useMemo(
+    () => withDynamicConfig(config, data),
+    [config, data]
+  );
+
+  return (
+    <Puck
+      plugins={plugins}
+      config={configWithDesignedComponents}
+      data={data}
+      onPublish={async (data) => {
+        await publishPuckPage({ data: { path, data } });
+      }}
+    />
+  );
+}
+
+function PuckSplatRoute() {
+  const { isEditorRoute, path, data } = Route.useLoaderData();
+
+  return isEditorRoute ? (
+    <Editor path={path} data={data} />
+  ) : (
+    <PuckRender data={data} />
+  );
+}

package/dist/templates/tanstack-start-ai/src/routes/__root.tsx

@@ -0,0 +1,42 @@
+import { HeadContent, Scripts, createRootRoute } from "@tanstack/react-router";
+
+import appCss from "../styles.css?url";
+
+export const Route = createRootRoute({
+  head: () => ({
+    meta: [
+      {
+        charSet: "utf-8",
+      },
+      {
+        name: "viewport",
+        content: "width=device-width, initial-scale=1",
+      },
+      {
+        title: "TanStack Start Starter",
+      },
+    ],
+    links: [
+      {
+        rel: "stylesheet",
+        href: appCss,
+      },
+    ],
+  }),
+  shellComponent: RootDocument,
+});
+
+function RootDocument({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        {children}
+
+        <Scripts />
+      </body>
+    </html>
+  );
+}

package/dist/templates/tanstack-start-ai/src/routes/api/puck/$.ts

@@ -0,0 +1,39 @@
+// Handles all requests for Puck AI
+// Learn more: https://puckeditor.com/docs/ai/getting-started
+import { createFileRoute } from "@tanstack/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\`
+      `,
+    },
+  },
+};
+
+const handleRequest = ({ request }: { request: Request }) =>
+  puckHandler(request, options);
+
+export const Route = createFileRoute("/api/puck/$")({
+  server: {
+    handlers: {
+      GET: handleRequest,
+      POST: handleRequest,
+      DELETE: handleRequest,
+    },
+  },
+});

package/dist/templates/tanstack-start-ai/src/routes/index.tsx

@@ -0,0 +1,18 @@
+import { createFileRoute } from "@tanstack/react-router";
+
+import { loadPuckPage } from "../lib/pages";
+import { PuckRender } from "../components/puck-render";
+
+export const Route = createFileRoute("/")({
+  loader: () => loadPuckPage({ data: "/" }),
+  head: ({ loaderData }) => ({
+    meta: [{ title: loaderData?.data.root.props?.title ?? "" }],
+  }),
+  component: Home,
+});
+
+function Home() {
+  const { data } = Route.useLoaderData();
+
+  return <PuckRender data={data} />;
+}

package/dist/templates/tanstack-start-ai/src/styles.css

@@ -0,0 +1,13 @@
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  font-family: system-ui, sans-serif;
+}
+
+main {
+  width: min(42rem, calc(100% - 2rem));
+  margin: 4rem auto;
+}

package/dist/templates/tanstack-start-ai/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "include": ["**/*.ts", "**/*.tsx"],
+  "compilerOptions": {
+    "target": "ES2022",
+    "jsx": "react-jsx",
+    "module": "ESNext",
+    "paths": {
+      "#/*": ["./src/*"],
+      "@/*": ["./src/*"]
+    },
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["vite/client"],
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  }
+}