\n\n> 🔒 **Upgrading to 0.9.1? Security release — the generated pages collection no longer defaults to allow-all writes.**\n>\n> - If you called `createPuckPlugin()` without an `access` option, your `pages` collection let **anonymous** callers create, update and delete through Payload's REST/GraphQL API. `create`, `update` and `delete` now default to any authenticated user; `read` stays public. Anything you pass explicitly still wins.\n> - **Action:** none if you already pass `access`. Otherwise decide who may write pages and say so, e.g. `access: { update: ({ req }) => req.user?.role === 'admin' }`. See the [CHANGELOG](./CHANGELOG.md#091---2026-09-09).\n\n---\n\n> 🔒 **Upgrading to 0.9? Security release — action required if you use the standalone route factories.**\n>\n> - **`createPuckApiRoutes`, `createPuckApiRoutesWithId`, `createPuckApiRoutesVersions` and `createPromptApiRoutes` now enforce Payload collection access control** ([GHSA-957g-hmmp-rchg](https://github.com/delmaredigital/payload-puck/security/advisories/GHSA-957g-hmmp-rchg)). They previously called Payload's Local API with the default `overrideAccess: true`, so collection and field `access` rules were **never evaluated** — any caller your `authenticate` hook accepted could read drafts and version history, restore versions over live content, publish, create and delete.\n> - **Action:** build `authenticate` on `payload.auth({ headers: request.headers })`. That works for **every** auth system — Better Auth, Clerk, NextAuth, custom strategies — and needs no other change. Do **not** return your auth library's session user, and do **not** map it back by email. Full steps in [Upgrading to 0.9.0](#upgrading-to-090-breaking-security).\n> - **Not affected:** the built-in `/api/puck/*` endpoints registered by `createPuckPlugin()`. Those were fixed in 0.6.23. If you never wired the standalone factories yourself, this release needs nothing from you.\n> - Also fixed: the AI context/prompts endpoints ([GHSA-rrx7-m589-5wfq](https://github.com/delmaredigital/payload-puck/security/advisories/GHSA-rrx7-m589-5wfq)) and the AI tools, which queried Payload unfiltered.\n\n---\n\n> 🎨 **Upgrading to 0.8?** The editor stylesheet is now built by your app, not by this plugin.\n>\n> - **`editorStylesheet`, `editorStylesheetCompiled` and `editorStylesheetUrls` are replaced by a single `editorStylesheets: string[]`** — an ordered list of URLs the editor iframe loads. The `/api/puck/styles` endpoint, the `/next` entry point and its `withPuckCSS()` wrapper, and the `postcss` / `postcss-load-config` peer dependencies are all removed.\n> - **Action:** install Tailwind's CLI (`pnpm add -D @tailwindcss/cli` on v4), add a `build:puck-css` script that compiles your CSS into `public/`, pass that URL via `editorStylesheets`, and delete the `withPuckCSS` wrapper from `next.config`. Full steps in [Upgrading to 0.8.0](#upgrading-to-080-breaking).\n> - **Why it matters:** the old design compiled CSS at runtime in development but relied on a **webpack plugin** in production. Next.js 16 defaults to Turbopack, which never runs `webpack()` hooks — so on Next 16 the production stylesheet was silently never generated and **the editor rendered completely unstyled in production while looking perfect locally**. If you are on Next 16, this release fixes that. See the [CHANGELOG](./CHANGELOG.md#080---2026-08-07).\n\n---\n\n> 📦 **Upgrading from 0.6.x?** `0.7.0` raised two floors before the 0.8 changes above: **`@puckeditor/core` now requires `>= 0.23.0`** (`pnpm add @puckeditor/core@^0.23.0`) and **Node 18 is no longer supported** (`node >= 20.9.0`). Puck 0.23 also ships a rewritten canvas drag-and-drop engine and a redesigned outline, so the editing experience changes visibly even though no API you call has changed — worth a pass through your editor. Apply both this and the 0.8 migration; see the [CHANGELOG](./CHANGELOG.md#070---2026-08-07).\n\n---\n\n## Documentation\n\n**[Full documentation →](https://delmaredigital.github.io/payload-puck/)**\n\n[](https://deepwiki.com/delmaredigital/payload-puck)\n\nCovers installation, configuration, components, custom fields, theming, layouts, dark mode, page-tree integration, hybrid integration, AI integration, and more.\n\n---\n\n## Install\n\n```bash\npnpm add @delmaredigital/payload-puck @puckeditor/core\n```\n\n### Requirements\n\n| Dependency | Version |\n|------------|---------|\n| `node` | >= 20.9.0 |\n| `@puckeditor/core` | >= 0.23.0 |\n| `payload` | >= 3.69.0 |\n| `@payloadcms/next` | >= 3.69.0 |\n| `next` | >= 15.4.8 (see security note below) |\n| `react` | >= 19.2.1 |\n\n> **Using [`@delmaredigital/payload-better-auth`](https://github.com/delmaredigital/payload-better-auth)?** Any published version works — its auth strategy stamps `collection` on the user, which is what 0.9's access resolution needs. **0.9.0 or later is recommended:** it is the first release where the recommended `payload.auth()` wiring, combined with the request headers 0.9 now forwards into Payload, is free of side effects for API-key requests. Current is `0.11.3`, which requires Better Auth `1.7`.\n\n> **Note:** Puck 0.21+ moved from `@measured/puck` to `@puckeditor/core`. This plugin requires the new package scope.\n\n> **Security:** If your app uses Next.js middleware (or proxy.ts) to protect dynamic routes, use `next` >= 15.5.16 / 16.2.5 to pick up the fix for [CVE-2026-44574](https://github.com/vercel/next.js/security/advisories/GHSA-492v-c6pp-mqqv) (middleware bypass via dynamic route parameter injection). Turbopack users need >= 15.5.18 / 16.2.6.\n\n### Upgrading to 0.9.0 (breaking, security)\n\n**Only affects apps that wired the standalone route factories from `@delmaredigital/payload-puck/api` or `/ai`.** The built-in `/api/puck/*` endpoints are unchanged.\n\nThese factories now pass `overrideAccess: false` to Payload, so your collection `access` rules are enforced. To do that they must know **which Payload user** a request acts as. Build `authenticate` on `payload.auth()`:\n\n```ts\nimport { getPayload } from 'payload'\nimport config from '@payload-config'\n\nexport const { GET, POST } = createPuckApiRoutes({\n collection: 'pages',\n payloadConfig: config,\n auth: {\n authenticate: async (request) => {\n const payload = await getPayload({ config })\n // Runs whatever auth strategies your Payload config registers.\n const { user } = await payload.auth({ headers: request.headers })\n if (!user) return { authenticated: false }\n return { authenticated: true, user }\n },\n },\n})\n```\n\nThis is the recommended wiring for **every** auth system, not just Payload's own. If you use Better Auth, keep `strategies: [betterAuthStrategy()]` on your users collection — that plus the snippet above is the whole integration.\n\n**Do not** return your auth library's session user (`auth.api.getSession()`, `getServerSession()`, `getServerUser()`, a decoded JWT). Those carry no `collection`, and these routes now fail closed on them with a `500` / `PUCK_ACCESS_MISCONFIGURED` and **no** database operation, with the fix printed to your server log.\n\n**Do not** map a session back to a user by email either — that is worse than the 500. A bare collection row silently drops the fields your auth strategy decorates onto the user; with `payload-better-auth` you lose `activeOrganizationId`, `organizationRole`, `apiKeyScopes` and `oauthScopes`, so an API-key caller can be judged as an ordinary session and an org-scoped rule evaluated with no organization at all.\n\nTwo smaller behaviour changes fall out of this:\n\n- **Denials are now `403`,** not `500`. A Payload `Forbidden` previously arrived as a server error, indistinguishable from an outage. `404` and `409` are likewise passed through.\n- **Request headers now reach your access rules.** They are forwarded into every Payload operation, so a rule that inspects them — an API-key scope check, say — sees the same request the REST API would.\n\nIf you are mid-migration and need to ship, `dangerouslyDisableCollectionAccessControl: true` restores the old behaviour and logs a warning once per factory. It leaves you with the vulnerability; treat it as a rollback, not a setting.\n\n### Upgrading to 0.8.0 (breaking)\n\n**Editor CSS is now built by your app, not by this plugin.** Three options collapse into one, and `withPuckCSS` is gone.\n\nAdd a build step using Tailwind's own CLI. Tailwind v4 ships the CLI as a separate package:\n\n```bash\npnpm add -D @tailwindcss/cli # v4 only; v3 already provides the `tailwindcss` binary\n```\n\n```jsonc\n// package.json — quote the paths; App Router route groups like (frontend) are shell syntax\n\"scripts\": {\n \"build:puck-css\": \"tailwindcss -i './src/app/(frontend)/globals.css' -o './public/puck-editor-styles.css'\",\n \"dev:puck-css\": \"tailwindcss -i './src/app/(frontend)/globals.css' -o './public/puck-editor-styles.css' --watch\",\n \"build\": \"pnpm build:puck-css && next build\",\n \"dev\": \"pnpm build:puck-css && next dev\"\n}\n```\n\nAdd `public/puck-editor-styles.css` to `.gitignore` — it's a build artifact. Run `dev:puck-css` in a second terminal while actively editing theme CSS.\n\nThen pass the URL:\n\n```typescript\n// before\ncreatePuckPlugin({\n editorStylesheet: 'src/app/(frontend)/globals.css',\n editorStylesheetCompiled: '/puck-editor-styles.css',\n editorStylesheetUrls: ['https://fonts.googleapis.com/css2?family=Inter'],\n})\n\n// after\ncreatePuckPlugin({\n editorStylesheets: ['/puck-editor-styles.css', 'https://fonts.googleapis.com/css2?family=Inter'],\n})\n```\n\nFinally, remove the `withPuckCSS` import and wrapper from `next.config.js`, and drop any `editorStylesheets` prop on `PuckConfigProvider` — the plugin wires it through automatically now.\n\n> **Why:** the old approach compiled CSS at runtime in dev and via a **webpack plugin** in production. Next.js 16 defaults to Turbopack, which never runs `webpack()` hooks — so the production stylesheet was silently never generated and the editor rendered unstyled, while local dev looked perfect. One artifact, built by your own toolchain, now resolves identically everywhere.\n\nAlso removed: the `/api/puck/styles` endpoint, the `/next` entry point, and the `postcss` / `postcss-load-config` peer dependencies.\n\n### Upgrading to 0.7.0 (breaking)\n\n`0.7.0` raises two floors. Both are a one-line change for most projects:\n\n```bash\npnpm add @puckeditor/core@^0.23.0 # peer floor moved from >=0.21.0\n```\n\n- **`@puckeditor/core` now requires >= 0.23.0.** The Puck plugins this package bundles are versioned in lockstep with Puck core and import it from the host, so running them against an older core is not a supported combination. Puck 0.23 ships a rewritten canvas drag-and-drop engine and a redesigned outline — **the editing experience changes visibly**, even though no API you call has changed. Worth a pass through your editor after upgrading. See the [Puck 0.23 release notes](https://puckeditor.com/blog/puck-023).\n- **Node 18 is no longer supported;** the floor is now `>=20.9.0`. Node 18 is end-of-life and Puck core 0.23 itself requires `>=20.0.0`.\n\nNo exports, props, or configuration options were removed or renamed. Full detail in the [changelog](./CHANGELOG.md).\n\n---\n\n## Quick Start\n\n### 1. Add the Plugin\n\n```typescript\n// src/payload.config.ts\nimport { buildConfig } from 'payload'\nimport { createPuckPlugin } from '@delmaredigital/payload-puck/plugin'\n\nexport default buildConfig({\n plugins: [\n createPuckPlugin({\n pagesCollection: 'pages',\n }),\n ],\n})\n```\n\n### 2. Provide Puck Configuration\n\n```typescript\n// app/(app)/layout.tsx\nimport { PuckConfigProvider } from '@delmaredigital/payload-puck/client'\nimport { editorConfig } from '@delmaredigital/payload-puck/config/editor'\n\nexport default function RootLayout({ children }: { children: React.ReactNode }) {\n return (\n \n \n \n {children}\n \n \n \n )\n}\n```\n\n### 3. Create a Frontend Route\n\n```typescript\n// app/(frontend)/[[...slug]]/page.tsx\nimport { getPayload } from 'payload'\nimport config from '@payload-config'\nimport { PageRenderer } from '@delmaredigital/payload-puck/render'\nimport { baseConfig } from '@delmaredigital/payload-puck/config'\nimport { notFound } from 'next/navigation'\n\nasync function getPage(slug?: string[]) {\n const payload = await getPayload({ config })\n const slugPath = slug?.join('/') || ''\n const { docs } = await payload.find({\n collection: 'pages',\n where: {\n and: [\n { _status: { equals: 'published' } },\n slugPath\n ? { slug: { equals: slugPath } }\n : { isHomepage: { equals: true } },\n ],\n },\n limit: 1,\n })\n return docs[0] || null\n}\n\nexport default async function Page({ params }: { params: Promise<{ slug?: string[] }> }) {\n const { slug } = await params\n const page = await getPage(slug)\n if (!page) notFound()\n return \n}\n```\n\nThat's it! The plugin registers the editor view, API endpoints, and \"Edit with Puck\" buttons automatically.\n\n---\n\n## Documentation\n\nFor everything else — components, custom fields, theming, layouts, dark mode, page-tree integration, hybrid integration, AI integration, advanced configuration, and the full export reference — see the [full documentation](https://delmaredigital.github.io/payload-puck/).\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md"}
![\"Starter](\"https://img.shields.io/badge/Starter_Template-Use_This-blue?style=for-the-badge&logo=github&logoColor=white\"){kind=icon}
\n