@puckeditor/cli 0.24.0-canary.301a0304

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

@@ -0,0 +1,113 @@
+# Puck + TanStack Start recipe
+
+[Puck](https://puckeditor.com) is the open-source visual editor for React.
+
+This recipe connects Puck 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
+/>
+```
+
+## 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`, `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. 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/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 publishing.** The `/edit` routes and `publishPuckPage` server function 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 `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)
+- [TanStack Start](https://tanstack.com/start/latest/docs/framework/react/overview)
+- [Puck Discord](https://discord.gg/D9e4E3MQVZ)

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

@@ -0,0 +1,26 @@
+{
+  "name": "tanstack-start-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/core": "workspace:*",
+    "@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/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/src/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/tanstack-start/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/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/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/src/routeTree.gen.ts

@@ -0,0 +1,86 @@
+/* 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/$'
+
+const IndexRoute = IndexRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const SplatRoute = SplatRouteImport.update({
+  id: '/$',
+  path: '/$',
+  getParentRoute: () => rootRouteImport,
+} as any)
+
+export interface FileRoutesByFullPath {
+  '/': typeof IndexRoute
+  '/$': typeof SplatRoute
+}
+export interface FileRoutesByTo {
+  '/': typeof IndexRoute
+  '/$': typeof SplatRoute
+}
+export interface FileRoutesById {
+  __root__: typeof rootRouteImport
+  '/': typeof IndexRoute
+  '/$': typeof SplatRoute
+}
+export interface FileRouteTypes {
+  fileRoutesByFullPath: FileRoutesByFullPath
+  fullPaths: '/' | '/$'
+  fileRoutesByTo: FileRoutesByTo
+  to: '/' | '/$'
+  id: '__root__' | '/' | '/$'
+  fileRoutesById: FileRoutesById
+}
+export interface RootRouteChildren {
+  IndexRoute: typeof IndexRoute
+  SplatRoute: typeof SplatRoute
+}
+
+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
+    }
+  }
+}
+
+const rootRouteChildren: RootRouteChildren = {
+  IndexRoute: IndexRoute,
+  SplatRoute: SplatRoute,
+}
+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/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/src/routes/$.tsx

@@ -0,0 +1,41 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { Puck } from "@puckeditor/core";
+
+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";
+
+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 }]
+      : [],
+  }),
+  component: PuckSplatRoute,
+});
+
+function PuckSplatRoute() {
+  const { isEditorRoute, path, data } = Route.useLoaderData();
+
+  return isEditorRoute ? (
+    <Puck
+      config={config}
+      data={data}
+      onPublish={async (data) => {
+        await publishPuckPage({ data: { path, data } });
+      }}
+    />
+  ) : (
+    <PuckRender data={data} />
+  );
+}

package/dist/templates/tanstack-start/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/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/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/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
+  }
+}

package/dist/templates/tanstack-start/vite.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from "vite";
+
+import { tanstackStart } from "@tanstack/react-start/plugin/vite";
+
+import viteReact from "@vitejs/plugin-react";
+
+const config = defineConfig({
+  resolve: { tsconfigPaths: true },
+  plugins: [tanstackStart(), viteReact()],
+  optimizeDeps: {
+    include: ["@puckeditor/core"],
+  },
+});
+
+export default config;