From 08ef13e44fbdd0c7ed94dc3c96e9126f8b2f4ed1 Mon Sep 17 00:00:00 2001 From: Vadym Samoilenko Date: Fri, 15 May 2026 15:54:36 +0100 Subject: [PATCH] vault backup: 2026-05-15 15:54:36 --- .../integrations__vercel-content-link.md | 0 wiki/_master-index.md | 2 +- wiki/payloadcms/_index.md | 1 + wiki/payloadcms/vercel-content-link.md | 122 ++++++++++++++++++ 4 files changed, 124 insertions(+), 1 deletion(-) rename raw/{ => _processed}/integrations__vercel-content-link.md (100%) create mode 100644 wiki/payloadcms/vercel-content-link.md diff --git a/raw/integrations__vercel-content-link.md b/raw/_processed/integrations__vercel-content-link.md similarity index 100% rename from raw/integrations__vercel-content-link.md rename to raw/_processed/integrations__vercel-content-link.md diff --git a/wiki/_master-index.md b/wiki/_master-index.md index b760145..15108e8 100644 --- a/wiki/_master-index.md +++ b/wiki/_master-index.md @@ -35,7 +35,7 @@ This 3-hop pattern works for hundreds of articles without vector search. | [[wiki/reports/_index\|reports/]] | Weekly and monthly summaries — generate: `uv run python scripts/report-generator.py --weekly` | 1 | | [[wiki/infrastructure/_index\|infrastructure/]] | Server inventory: all 10 SSH hosts — optical, optical-dev, optical-prod, baic, librechat, modocmms, box-cli, aimpress, pve | 12 | | [[wiki/testing/_index\|testing/]] | Web app testing: functional, performance, security, UI types; TDD/BDD/Agile methodologies; Selenium/Cypress/Playwright/JMeter/OWASP ZAP tools | 1 | -| [[wiki/payloadcms/_index\|payloadcms/]] | Full Payload CMS reference — getting started, config, database (Postgres/MongoDB/SQLite), all 22 field types, access control, hooks, authentication (cookies, JWT, API keys, custom strategies, token data), admin UI, custom components, Lexical rich text, live preview, versions/drafts, Local/REST/GraphQL APIs, queries, plugins, jobs queue, upload, ecommerce, production deploy, TypeScript, migration guides, i18n, localization, hierarchy | 95 | +| [[wiki/payloadcms/_index\|payloadcms/]] | Full Payload CMS reference — getting started, config, database (Postgres/MongoDB/SQLite), all 22 field types, access control, hooks, authentication (cookies, JWT, API keys, custom strategies, token data), admin UI, custom components, Lexical rich text, live preview, versions/drafts, Local/REST/GraphQL APIs, queries, plugins, jobs queue, upload, ecommerce, production deploy, TypeScript, migration guides, i18n, localization, hierarchy | 96 | | [[wiki/shared-patterns/_index\|shared-patterns/]] | Oliver Agency standard library patterns: httpx, structlog, pydantic-settings, alembic — reuse before writing from scratch | 4 | | [[wiki/mistakes/_index\|mistakes/]] | Anti-patterns extracted from sessions — per-stack running lists (fastapi, react, docker, postgres, general) — injected at session start | 5 | diff --git a/wiki/payloadcms/_index.md b/wiki/payloadcms/_index.md index 6f23af6..8fce6af 100644 --- a/wiki/payloadcms/_index.md +++ b/wiki/payloadcms/_index.md @@ -94,6 +94,7 @@ | [[wiki/payloadcms/hooks-fields\|Field Hooks]] | Per-field lifecycle hooks: beforeValidate, beforeChange, afterChange, afterRead, beforeDuplicate — args reference, patterns, TypeScript generics | raw/hooks__fields.md | 2026-05-15 | | [[wiki/payloadcms/hooks-globals\|Global Hooks]] | All 6 Global hook types: beforeOperation/Validate/Change/Read, afterChange/Read — args tables, data vs originalDoc gotcha, TS generics | raw/hooks__globals.md | 2026-05-15 | | [[wiki/payloadcms/installation\|Installation]] | Requirements (Node 24+, Next.js 16.2.6+), create-payload-app quickstart, manual install steps, withPayload ESM config, tsconfig path alias | raw/getting-started__installation.md | 2026-05-15 | +| [[wiki/payloadcms/vercel-content-link\|Vercel Content Link]] | Enterprise visual editing: stega Content Source Maps, `@payloadcms/plugin-csm` setup, encodeSourceMaps flag, blocks/_encodedSourceMap, date field split | raw/integrations__vercel-content-link.md | 2026-05-15 | | [[wiki/payloadcms/graphql-extending\|GraphQL — Custom Queries and Mutations]] | Add custom GraphQL ops via `graphQL.queries`/`graphQL.mutations` in buildConfig; resolver signature, `depth: 0` gotcha, `buildPaginatedListType`, collection graphQL types | raw/graphql__extending.md | 2026-05-15 | | [[wiki/payloadcms/graphql-schema\|GraphQL — Schema Generation]] | `payload-graphql generate:schema` CLI, PAYLOAD_CONFIG_PATH for non-root configs, `interfaceName` for reusable top-level GraphQL types | raw/graphql__graphql-schema.md | 2026-05-15 | | [[wiki/payloadcms/hierarchy\|Hierarchy — Tree Structure]] | Auto-generated parent-child trees: virtual slug/title paths, opt-in path computation, polymorphic hierarchies, no cascade updates | raw/hierarchy__overview.md | 2026-05-15 | diff --git a/wiki/payloadcms/vercel-content-link.md b/wiki/payloadcms/vercel-content-link.md new file mode 100644 index 0000000..11ab22e --- /dev/null +++ b/wiki/payloadcms/vercel-content-link.md @@ -0,0 +1,122 @@ +--- +title: "Vercel Content Link" +aliases: [vercel-csm, content-source-maps, visual-editing-vercel] +tags: [payloadcms, vercel, visual-editing, integrations, enterprise] +sources: [raw/integrations__vercel-content-link.md] +created: 2026-05-15 +updated: 2026-05-15 +--- + +## Overview + +Vercel Content Link lets editors click any rendered text on a Vercel preview and jump directly to the Payload field that controls it. Payload embeds **Content Source Maps** (invisible stega-encoded JSON) in API responses; Vercel's toolbar decodes them and highlights editable fields in blue. + +**Enterprise-only** — requires `@payloadcms/plugin-csm` and an API key from Payload sales. Works only on Vercel-hosted deployments. + +--- + +## Setup + +### 1. Install plugin + +```bash +npm i @payloadcms/plugin-csm +``` + +### 2. Register in Payload config + +```ts +import contentSourceMaps from '@payloadcms/plugin-csm' + +export default buildConfig({ + plugins: [ + contentSourceMaps({ + collections: ['pages'], // opt-in per collection + }), + ], +}) +``` + +### 3. Enable encoding in Next.js (draft/preview only) + +**REST API:** +```ts +if (isDraftMode || process.env.VERCEL_ENV === 'preview') { + const res = await fetch( + `${process.env.NEXT_PUBLIC_PAYLOAD_CMS_URL}/api/pages?encodeSourceMaps=true&where[slug][equals]=${slug}`, + ) +} +``` + +**Local API:** +```ts +if (isDraftMode || process.env.VERCEL_ENV === 'preview') { + const res = await payload.find({ + collection: 'pages', + where: { slug: { equals: slug } }, + context: { encodeSourceMaps: true }, + }) +} +``` + +> Only enable `encodeSourceMaps` in draft mode or preview deployments — it adds encoding overhead. + +--- + +## Edit Mode + +1. Visit any **preview deployment** on Vercel. +2. Log in via the **Vercel Toolbar**. +3. When CSMs are detected, a pencil icon appears → click to enter **Edit Mode**. +4. All editable fields are highlighted in blue with click-through links to Payload. + +--- + +## Troubleshooting + +### Date fields +Date fields are not encoded by default. If negative `letter-spacing` CSS causes rendering issues, split the encoded value: + +```ts +import { vercelStegaSplit } from '@vercel/stega' +const { cleaned, encoded } = vercelStegaSplit(text) +// use `cleaned` for rendering, `encoded` carries the source map +``` + +### Blocks and array fields +`blocks` and `array` fields have no plain text to encode. They receive an `_encodedSourceMap` property instead. Use it to make entire sections clickable: + +```tsx +
+ {_encodedSourceMap} + {children} +
+``` + +--- + +## Key Takeaways + +- **Enterprise only** — needs API key + `@payloadcms/plugin-csm`. +- Payload injects stega-encoded Content Source Maps into REST and Local API responses via the `encodeSourceMaps` flag. +- Only enable encoding in **draft mode / preview** to avoid production overhead. +- `date` fields are excluded from encoding by default — use `vercelStegaSplit` if needed. +- `blocks` / `array` fields get `_encodedSourceMap` property + `data-vercel-edit-target` for section-level editing. +- No changes required to frontend rendering code beyond adding `encodeSourceMaps=true` to queries. + +--- + +## Related + +- [[wiki/payloadcms/admin-preview|Admin Preview & Draft Preview]] — draft mode setup in Next.js +- [[wiki/payloadcms/live-preview|Live Preview]] — Payload's own iframe live preview (no Vercel required) +- [[wiki/payloadcms/plugins|Official Plugins]] — full plugin registry +- [[wiki/payloadcms/rest-api|REST API]] — query params reference +- [[wiki/payloadcms/local-api|Local API]] — `context` property usage + +--- + +## Sources + +- [Vercel Content Link — Payload Docs](https://payloadcms.com/docs/integrations/vercel-content-link) +- [`@vercel/stega` on npm](https://www.npmjs.com/package/@vercel/stega)