@decocms/blocks 8.10.0 → 8.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (210) hide show
  1. package/dist/index.d.ts +1 -1
  2. package/dist/index.d.ts.map +1 -1
  3. package/dist/index.js.map +1 -1
  4. package/dist/protocol/conformance/blockMetaVectors.json +80 -0
  5. package/dist/protocol/index.d.ts +5 -2
  6. package/dist/protocol/index.d.ts.map +1 -1
  7. package/dist/protocol/index.js +5 -2
  8. package/dist/protocol/index.js.map +1 -1
  9. package/dist/v8/blockMeta.d.ts +33 -4
  10. package/dist/v8/blockMeta.d.ts.map +1 -1
  11. package/dist/v8/blockMeta.js +70 -13
  12. package/dist/v8/blockMeta.js.map +1 -1
  13. package/dist/v8/cli/index.d.ts +1 -0
  14. package/dist/v8/cli/index.d.ts.map +1 -1
  15. package/dist/v8/cli/index.js +1 -0
  16. package/dist/v8/cli/index.js.map +1 -1
  17. package/dist/v8/cli/run.d.ts +2 -0
  18. package/dist/v8/cli/run.d.ts.map +1 -1
  19. package/dist/v8/cli/run.js +30 -1
  20. package/dist/v8/cli/run.js.map +1 -1
  21. package/dist/v8/cli/skills.d.ts +25 -0
  22. package/dist/v8/cli/skills.d.ts.map +1 -0
  23. package/dist/v8/cli/skills.js +70 -0
  24. package/dist/v8/cli/skills.js.map +1 -0
  25. package/dist/v8/client.d.ts +6 -4
  26. package/dist/v8/client.d.ts.map +1 -1
  27. package/dist/v8/client.js +26 -70
  28. package/dist/v8/client.js.map +1 -1
  29. package/dist/v8/cms.d.ts.map +1 -1
  30. package/dist/v8/cms.js +1 -2
  31. package/dist/v8/cms.js.map +1 -1
  32. package/dist/v8/contentIndex.d.ts +18 -7
  33. package/dist/v8/contentIndex.d.ts.map +1 -1
  34. package/dist/v8/contentIndex.js +46 -17
  35. package/dist/v8/contentIndex.js.map +1 -1
  36. package/dist/v8/draftChanges.d.ts.map +1 -1
  37. package/dist/v8/draftChanges.js +4 -1
  38. package/dist/v8/draftChanges.js.map +1 -1
  39. package/dist/v8/index.d.ts +1 -1
  40. package/dist/v8/index.d.ts.map +1 -1
  41. package/dist/v8/remoteLoader.d.ts +4 -2
  42. package/dist/v8/remoteLoader.d.ts.map +1 -1
  43. package/dist/v8/remoteLoader.js +13 -3
  44. package/dist/v8/remoteLoader.js.map +1 -1
  45. package/dist/v8/types.d.ts +47 -7
  46. package/dist/v8/types.d.ts.map +1 -1
  47. package/package.json +3 -2
  48. package/skills/deco-apps/SKILL.md +82 -0
  49. package/skills/deco-apps/references/algolia.md +51 -0
  50. package/skills/deco-apps/references/commerce-types.md +132 -0
  51. package/skills/deco-apps/references/instrumented-fetch.md +144 -0
  52. package/skills/deco-apps/references/magento.md +55 -0
  53. package/skills/deco-apps/references/messaging.md +76 -0
  54. package/skills/deco-apps/references/shopify.md +69 -0
  55. package/skills/deco-apps/references/vendored-loaders.md +135 -0
  56. package/skills/deco-apps/references/vtex-cookies-auth.md +146 -0
  57. package/skills/deco-apps/references/vtex.md +150 -0
  58. package/skills/deco-apps/references/wake.md +75 -0
  59. package/skills/deco-cms-schema/SKILL.md +80 -0
  60. package/skills/deco-cms-schema/references/annotations.md +147 -0
  61. package/skills/deco-cms-schema/references/content-hygiene.md +91 -0
  62. package/skills/deco-cms-schema/references/formats-and-widgets.md +112 -0
  63. package/skills/deco-cms-schema/references/shapes-that-break-the-form.md +165 -0
  64. package/skills/deco-cms-schema/references/types-to-fields.md +112 -0
  65. package/skills/deco-go-live/SKILL.md +127 -0
  66. package/skills/deco-go-live/references/content-releases.md +90 -0
  67. package/skills/deco-go-live/references/process.md +106 -0
  68. package/skills/deco-go-live/references/proxy-headers-checkout.md +139 -0
  69. package/skills/deco-go-live/references/qa-checklist-template.md +150 -0
  70. package/skills/deco-go-live/references/qa-inventory.md +120 -0
  71. package/skills/deco-go-live/references/react-spa.md +183 -0
  72. package/skills/deco-go-live/references/seo-analytics.md +114 -0
  73. package/skills/deco-go-live/references/traffic-ramp.md +87 -0
  74. package/skills/deco-go-live/references/worker-runtime.md +93 -0
  75. package/skills/deco-go-live/scripts/preflight.sh +221 -0
  76. package/skills/deco-images-media/SKILL.md +64 -0
  77. package/skills/deco-images-media/references/asset-upload.md +191 -0
  78. package/skills/deco-images-media/references/components-per-binding.md +167 -0
  79. package/skills/deco-images-media/references/providers-and-cdn.md +145 -0
  80. package/skills/deco-images-media/references/quality-and-lcp.md +93 -0
  81. package/skills/deco-images-media/references/troubleshooting.md +147 -0
  82. package/skills/deco-images-media/references/video.md +122 -0
  83. package/skills/deco-make-editable/SKILL.md +94 -0
  84. package/skills/deco-make-editable/references/a11y-and-e2e.md +104 -0
  85. package/skills/deco-make-editable/references/content-shapes.md +203 -0
  86. package/skills/deco-make-editable/references/from-figma.md +110 -0
  87. package/skills/deco-make-editable/references/i18n-fields.md +112 -0
  88. package/skills/deco-make-editable/references/inventory.md +79 -0
  89. package/skills/deco-make-editable/references/pixel-parity.md +175 -0
  90. package/skills/deco-make-editable/references/seeding-content.md +119 -0
  91. package/skills/deco-nextjs-site/SKILL.md +74 -0
  92. package/skills/deco-nextjs-site/references/caching.md +116 -0
  93. package/skills/deco-nextjs-site/references/metadata-seo.md +100 -0
  94. package/skills/deco-nextjs-site/references/proxy-and-drafts.md +177 -0
  95. package/skills/deco-nextjs-site/references/rendering.md +172 -0
  96. package/skills/deco-nextjs-site/references/setup.md +190 -0
  97. package/skills/deco-nextjs-site/references/studio-bridge.md +130 -0
  98. package/skills/deco-site-authoring/SKILL.md +75 -0
  99. package/skills/deco-site-authoring/references/lazy-blocks.md +155 -0
  100. package/skills/deco-site-authoring/references/loaders.md +192 -0
  101. package/skills/deco-site-authoring/references/pages.md +158 -0
  102. package/skills/deco-site-authoring/references/review-before-publish.md +95 -0
  103. package/skills/deco-site-authoring/references/sections.md +158 -0
  104. package/skills/deco-site-authoring/references/seo.md +116 -0
  105. package/skills/deco-site-workflow/SKILL.md +101 -0
  106. package/skills/deco-site-workflow/references/check.md +116 -0
  107. package/skills/deco-site-workflow/references/cli-reference.md +106 -0
  108. package/skills/deco-site-workflow/references/content-layout.md +93 -0
  109. package/skills/deco-site-workflow/references/content-sync.md +146 -0
  110. package/skills/deco-site-workflow/references/delivery.md +51 -0
  111. package/skills/deco-site-workflow/references/deploy.md +87 -0
  112. package/skills/deco-site-workflow/references/schema.md +173 -0
  113. package/skills/deco-site-workflow/references/serve-and-studio.md +138 -0
  114. package/skills/deco-storefront-caching/SKILL.md +67 -0
  115. package/skills/deco-storefront-caching/references/cache-keys.md +129 -0
  116. package/skills/deco-storefront-caching/references/case-study.md +82 -0
  117. package/skills/deco-storefront-caching/references/egress-traps.md +153 -0
  118. package/skills/deco-storefront-caching/references/nextjs.md +60 -0
  119. package/skills/deco-storefront-caching/references/perf-guardrails-e2e.md +123 -0
  120. package/skills/deco-storefront-caching/references/verification.md +136 -0
  121. package/skills/deco-storefront-caching/references/worker-page-cache.md +160 -0
  122. package/skills/deco-storefront-caching/scripts/html-anatomy.mjs +97 -0
  123. package/skills/deco-storefront-performance/SKILL.md +81 -0
  124. package/skills/deco-storefront-performance/references/cls-third-party.md +90 -0
  125. package/skills/deco-storefront-performance/references/hydration.md +116 -0
  126. package/skills/deco-storefront-performance/references/loaders-n-plus-1.md +107 -0
  127. package/skills/deco-storefront-performance/references/navigation-ux.md +130 -0
  128. package/skills/deco-storefront-performance/references/payload-trim.md +163 -0
  129. package/skills/deco-storefront-performance/references/render-location.md +152 -0
  130. package/skills/deco-storefront-performance/references/request-dedupe.md +147 -0
  131. package/skills/deco-storefront-performance/references/trace-reading.md +79 -0
  132. package/skills/deco-storefront-performance/references/worker-memory.md +176 -0
  133. package/skills/deco-tanstack-site/SKILL.md +68 -0
  134. package/skills/deco-tanstack-site/references/document-and-security.md +155 -0
  135. package/skills/deco-tanstack-site/references/router-and-navigation.md +137 -0
  136. package/skills/deco-tanstack-site/references/routes-and-pages.md +183 -0
  137. package/skills/deco-tanstack-site/references/server-functions.md +123 -0
  138. package/skills/deco-tanstack-site/references/setup.md +153 -0
  139. package/skills/deco-tanstack-site/references/worker-entry.md +152 -0
  140. package/skills/deco-v7-to-v8-migration/SKILL.md +123 -0
  141. package/skills/deco-v7-to-v8-migration/references/caching-and-privacy.md +10 -0
  142. package/skills/deco-v7-to-v8-migration/references/content.md +25 -0
  143. package/skills/deco-v7-to-v8-migration/references/editor-forms.md +27 -0
  144. package/skills/deco-v7-to-v8-migration/references/faststore.md +40 -0
  145. package/skills/deco-v7-to-v8-migration/references/framework-code.md +53 -0
  146. package/skills/deco-v7-to-v8-migration/references/hosted-releases.md +16 -0
  147. package/skills/deco-v7-to-v8-migration/references/import-map.md +81 -0
  148. package/skills/deco-v7-to-v8-migration/references/legacy-names.md +33 -0
  149. package/skills/deco-v7-to-v8-migration/references/manual-steps.md +10 -0
  150. package/skills/deco-v7-to-v8-migration/references/native-apps.md +43 -0
  151. package/skills/deco-v7-to-v8-migration/references/nextjs.md +19 -0
  152. package/skills/deco-v7-to-v8-migration/references/parity.md +66 -0
  153. package/skills/deco-v7-to-v8-migration/references/rendering.md +13 -0
  154. package/skills/deco-v7-to-v8-migration/references/running-the-script.md +29 -0
  155. package/skills/deco-v7-to-v8-migration/references/script-steps.md +13 -0
  156. package/skills/deco-v7-to-v8-migration/references/server-functions.md +15 -0
  157. package/skills/deco-v7-to-v8-migration/references/sibling-port.md +11 -0
  158. package/skills/deco-v7-to-v8-migration/references/site-code.md +15 -0
  159. package/skills/deco-v7-to-v8-migration/references/telemetry.md +10 -0
  160. package/skills/deco-v7-to-v8-migration/references/verify.md +23 -0
  161. package/skills/deco-v7-to-v8-migration/scripts/apps.ts +297 -0
  162. package/skills/deco-v7-to-v8-migration/scripts/asyncRendering.ts +73 -0
  163. package/skills/deco-v7-to-v8-migration/scripts/blockMap.ts +584 -0
  164. package/skills/deco-v7-to-v8-migration/scripts/checkContentReads.ts +32 -0
  165. package/skills/deco-v7-to-v8-migration/scripts/ciSchemaCheck.ts +145 -0
  166. package/skills/deco-v7-to-v8-migration/scripts/compat.ts +357 -0
  167. package/skills/deco-v7-to-v8-migration/scripts/content.ts +121 -0
  168. package/skills/deco-v7-to-v8-migration/scripts/contentReads.ts +157 -0
  169. package/skills/deco-v7-to-v8-migration/scripts/experiments.ts +81 -0
  170. package/skills/deco-v7-to-v8-migration/scripts/framework.ts +61 -0
  171. package/skills/deco-v7-to-v8-migration/scripts/imageCopy.ts +276 -0
  172. package/skills/deco-v7-to-v8-migration/scripts/imageModule.ts +285 -0
  173. package/skills/deco-v7-to-v8-migration/scripts/imports.ts +942 -0
  174. package/skills/deco-v7-to-v8-migration/scripts/invoke.ts +624 -0
  175. package/skills/deco-v7-to-v8-migration/scripts/legacyNames.ts +45 -0
  176. package/skills/deco-v7-to-v8-migration/scripts/main.ts +59 -0
  177. package/skills/deco-v7-to-v8-migration/scripts/matchers.ts +41 -0
  178. package/skills/deco-v7-to-v8-migration/scripts/migrate.ts +180 -0
  179. package/skills/deco-v7-to-v8-migration/scripts/redirects.ts +455 -0
  180. package/skills/deco-v7-to-v8-migration/scripts/report.ts +50 -0
  181. package/skills/deco-v7-to-v8-migration/scripts/scaffold.ts +1119 -0
  182. package/skills/deco-v7-to-v8-migration/scripts/secrets.ts +35 -0
  183. package/skills/deco-v7-to-v8-migration/scripts/sectionLoaders.ts +216 -0
  184. package/skills/deco-v7-to-v8-migration/scripts/siteSettings.ts +261 -0
  185. package/skills/deco-v7-to-v8-migration/scripts/stubs.ts +388 -0
  186. package/skills/deco-v7-to-v8-migration/scripts/tsconfig.json +7 -0
  187. package/skills/deco-v7-to-v8-migration/scripts/vendor.ts +249 -0
  188. package/skills/deco-v7-to-v8-migration/scripts/vtexInvoke.ts +240 -0
  189. package/skills/deco-v7-to-v8-migration/scripts/walk.ts +30 -0
  190. package/skills/deco-variants/SKILL.md +57 -0
  191. package/skills/deco-variants/references/caching-variants.md +63 -0
  192. package/skills/deco-variants/references/custom-matchers.md +83 -0
  193. package/skills/deco-variants/references/draft-preview.md +59 -0
  194. package/skills/deco-variants/references/experiments-and-campaigns.md +104 -0
  195. package/skills/deco-variants/references/multivariate.md +85 -0
  196. package/skills/deco-variants/references/v7-matchers.md +71 -0
  197. package/src/index.ts +1 -1
  198. package/src/protocol/conformance/blockMetaVectors.json +80 -0
  199. package/src/protocol/index.ts +8 -1
  200. package/src/v8/blockMeta.ts +75 -11
  201. package/src/v8/cli/index.ts +1 -0
  202. package/src/v8/cli/run.ts +35 -1
  203. package/src/v8/cli/skills.ts +91 -0
  204. package/src/v8/client.ts +32 -77
  205. package/src/v8/cms.ts +1 -2
  206. package/src/v8/contentIndex.ts +49 -19
  207. package/src/v8/draftChanges.ts +5 -1
  208. package/src/v8/index.ts +1 -1
  209. package/src/v8/remoteLoader.ts +13 -3
  210. package/src/v8/types.ts +48 -7
@@ -0,0 +1,110 @@
1
+ # From a Figma file to editable sections
2
+
3
+ The same method as a hardcoded site, with the design as the source: map the
4
+ file, build each section with typed props, seed the blocks with the design's
5
+ content, then compare with the design (see [pixel-parity.md](./pixel-parity.md)).
6
+
7
+ The Figma tools named here (`get_metadata`, `get_design_context`,
8
+ `get_screenshot`, `get_variable_defs`) belong to the Figma MCP server, not to
9
+ this repo. Follow that server's own instructions: it may ask for a session or
10
+ a design-to-code skill before the first read.
11
+
12
+ ## 1. Map the file
13
+
14
+ Take the file key from the URL (`figma.com/design/<fileKey>/<name>?node-id=1-2`;
15
+ a `node-id` of `1-2` is node `1:2`). Call `get_metadata` on the root node to
16
+ list pages and their top-level frames.
17
+
18
+ Map Figma pages to routes, and say which ones are not pages:
19
+
20
+ | Figma page | Route | Shape |
21
+ |---|---|---|
22
+ | Home | `/` | composed page |
23
+ | Landing / Campaign | `/campaign/...` | composed page |
24
+ | Institutional (About, Contact) | `/about`, `/contact` | composed page |
25
+ | Blog | `/blog`, `/blog/:slug` | collection (see [content-shapes.md](./content-shapes.md)) |
26
+ | Product listing, product detail, search, cart | the site's commerce routes | sections fed by loaders; see `deco-site-authoring` and `deco-apps` |
27
+ | Components / Design system | none | reusable parts, not a page |
28
+
29
+ Call `get_metadata` on each page node. Each top-level frame is usually one
30
+ section. Record for each: node id, name, page, width and position (top to
31
+ bottom is render order).
32
+
33
+ - **Desktop and mobile:** frames named `Hero - Desktop` and `Hero - Mobile`
34
+ are one section with two layouts. Frames wider than 1024px are desktop;
35
+ 375px is the usual mobile width. With only a desktop frame, build the mobile
36
+ layout with responsive styles and confirm it with the designer.
37
+ - **Shared or page-specific:** the header and footer appear on every page:
38
+ global blocks. A newsletter band on several pages is one section type used
39
+ in several pages, not a global block, unless editors want to change it in
40
+ one place.
41
+
42
+ ## 2. The section map
43
+
44
+ Before writing code, produce a table and get the user's confirmation:
45
+
46
+ | # | Section | Figma page | Node | Shape | Variants | Data | Interactive parts |
47
+ |---|---|---|---|---|---|---|---|
48
+ | 1 | Header | all | 12:34 | global block | desktop, mobile | none | mobile menu, search |
49
+ | 2 | Hero | Home | 12:56 | page section | desktop, mobile | none | carousel |
50
+ | 3 | ProductShelf | Home | 13:10 | page section | desktop | product list loader | none |
51
+
52
+ Build in this order: header, footer, the home's first section, the rest of the
53
+ home top to bottom, then the other pages. The header and footer are on every
54
+ screenshot, so getting them right first makes every later comparison cleaner.
55
+
56
+ ## 3. Design tokens
57
+
58
+ Call `get_variable_defs` on a frame to read the file's variables (colors,
59
+ spacing, type, radii). Match them to the site's existing theme first (Tailwind
60
+ config, CSS variables). Add a token only when no existing one matches, and
61
+ name it as the design names it. A section that hardcodes `#1a1a2e` where the
62
+ theme has `--color-secondary` drifts the first time the brand changes.
63
+
64
+ ## 4. Build each section
65
+
66
+ Call `get_design_context` on the frame (and on its mobile frame). It returns
67
+ reference markup, a screenshot and asset URLs. The markup is a reference to
68
+ adapt to the site's components and tokens, not code to paste.
69
+
70
+ For each section:
71
+
72
+ - **Props are the content.** Every text, link, image and list an editor could
73
+ change is a prop. Type them for the form (`deco-cms-schema`); an image is a
74
+ string typed `ImageWidget` (from `@decocms/compat-v7/types/widgets`, or any
75
+ local `type ImageWidget = string`: `deco schema` reads the name) so Studio
76
+ shows an image picker.
77
+ - **No content in default values.** The design's texts go into the seeded
78
+ blocks ([seeding-content.md](./seeding-content.md)), not into default
79
+ parameters. Defaults in code are a second copy of the content.
80
+ - **Interactive parts are small client components.** A carousel, an accordion
81
+ or a menu drawer is its own component with state; the section around it
82
+ stays plain. The examples in this repo mark such components `"use client"`,
83
+ which matters for React Server Components (Next.js). Pass them serializable
84
+ props only. `deco-site-authoring` covers this.
85
+ - **Data comes from loaders.** A shelf that shows products takes them from a
86
+ loader block, not from a fetch inside the component. See
87
+ `deco-site-authoring` and `deco-apps`.
88
+ - **Images:** render with `Image` or `Picture` from `@decocms/tanstack/react`
89
+ (or `next/image` with the deco loader on Next.js), always with `width` and
90
+ `height`. Set `preload` on the one image that is the page's LCP, usually the
91
+ first hero image; every other `Image` loads lazily by default.
92
+ - Add the section to the block map and run `deco schema`.
93
+
94
+ ## 5. Assets
95
+
96
+ The asset URLs from `get_design_context` are temporary Figma exports. Download
97
+ them, prefer the original files when the designer can export them, and put
98
+ them where the site's images live. The `deco` CLI has no asset upload command;
99
+ `deco-images-media` covers where images go and how their URLs are served.
100
+ Use the final URLs in the seeded blocks.
101
+
102
+ ## 6. Assemble the pages
103
+
104
+ Write one `page` block per Figma page, with its sections in the design's order
105
+ and the design's content in each section
106
+ ([content-shapes.md](./content-shapes.md#composed-pages)). Write the global
107
+ blocks (header, footer). Run `deco check`, or push to a draft and run
108
+ `deco check --draft=<name>` on a hosted site.
109
+
110
+ Then compare with the design: [pixel-parity.md](./pixel-parity.md#against-a-figma-design).
@@ -0,0 +1,112 @@
1
+ # Two languages: one block, `foo` and `fooPt`
2
+
3
+ `@decocms/blocks` 8 has no locale concept for content. A site with two
4
+ languages decides how content carries both. This is the convention that held
5
+ up in a real conversion of a two-language site. Rename `Pt` for your secondary
6
+ language.
7
+
8
+ ## The options, and why this one
9
+
10
+ | Option | Problem |
11
+ |---|---|
12
+ | One block per language (`Header menu`, `Header menu PT`) | Every change is made twice, and the two drift. The editors who tried it rejected it. |
13
+ | Variants that pick a language by path | Every block holds two full copies of its content, and the language rule repeats in every block. |
14
+ | An object per field (`title: { en, pt }`) | Form tags that name a string field, such as `@titleBy` for a list item's title, have no flat string to point at. |
15
+ | **A sibling field: `title` and `titlePt`** | Fields stay flat. One block, both languages side by side in the form. |
16
+
17
+ ## The convention
18
+
19
+ - **One block per piece of content, never one per language.**
20
+ - Any text field `foo` may have a sibling `fooPt`. Pages in the secondary
21
+ language show `fooPt` when it is filled and fall back to `foo` when it is
22
+ empty.
23
+ - **Sections read only `foo`.** One `localize(props, locale)` call, where the
24
+ site renders blocks, picks the language. No section knows about `Pt`.
25
+ - **Links are written without the locale prefix.** The component adds `/pt`
26
+ for the secondary language. Editors write `/pricing` once.
27
+ - Say it in the form: give each `fooPt` a description such as "Shown on
28
+ Portuguese pages. When empty, the English text is used." (`deco-cms-schema`
29
+ lists the JSDoc tags the form reads.)
30
+
31
+ ```ts
32
+ // src/sections/HeaderMenu.tsx
33
+ export interface NavigationLink {
34
+ /** @title Label (English) */
35
+ label: string;
36
+ /**
37
+ * @title Label (Português)
38
+ * @description Shown on Portuguese pages. When empty, the English label is used.
39
+ */
40
+ labelPt?: string;
41
+ /**
42
+ * @title Link
43
+ * @description A path such as /pricing. Portuguese pages add /pt automatically.
44
+ */
45
+ href: string;
46
+ }
47
+
48
+ export interface HeaderMenuProps {
49
+ links: NavigationLink[];
50
+ }
51
+ ```
52
+
53
+ ## `localize`
54
+
55
+ Block results are read-only: a client hands the same object to every place
56
+ that uses the same block in a request. `localize` builds a new object and never
57
+ changes its input.
58
+
59
+ ```ts
60
+ // src/localize.ts
61
+ export type Locale = "en" | "pt";
62
+ const SUFFIX = "Pt";
63
+
64
+ /** `fooPt` replaces `foo` on secondary-language pages when filled; `*Pt` keys are dropped. */
65
+ export function localize<T>(value: T, locale: Locale): T {
66
+ if (Array.isArray(value)) return value.map((item) => localize(item, locale)) as T;
67
+ if (!value || typeof value !== "object") return value;
68
+ const source = value as Record<string, unknown>;
69
+ const result: Record<string, unknown> = {};
70
+ for (const [key, child] of Object.entries(source)) {
71
+ // Drop `fooPt` only when `foo` exists, so a field that is really named `ctaPt` survives.
72
+ if (key.endsWith(SUFFIX) && key.length > SUFFIX.length && key.slice(0, -SUFFIX.length) in source) continue;
73
+ const translated = source[`${key}${SUFFIX}`];
74
+ const useTranslation = locale === "pt" && typeof translated === "string" && translated.trim() !== "";
75
+ result[key] = useTranslation ? translated : localize(child, locale);
76
+ }
77
+ return result as T;
78
+ }
79
+ ```
80
+
81
+ Write a unit test for it: a nested list, an empty `fooPt`, a field genuinely
82
+ named `somethingPt` without a `something`.
83
+
84
+ ## Where the language comes from
85
+
86
+ A block function receives only its saved input, so the language is never
87
+ decided inside the block map. The site decides it from the request (the path
88
+ prefix, usually) and applies `localize` where it renders:
89
+
90
+ - **Descriptors:** the code that maps `{ component, props }` to a component
91
+ calls `localize(props, locale)` and passes `locale` as an extra prop, outside
92
+ the `Props` type, so it never appears in the form.
93
+ - **JSX blocks:** the component reads the language from the site's own React
94
+ context and calls `localize` on its props.
95
+
96
+ ## Routing the secondary language
97
+
98
+ Both languages render the **same** page block. The secondary-language route
99
+ removes its prefix before matching, so `/pt/pricing` finds the page whose
100
+ `path` is `/pricing`, and only `locale` changes:
101
+
102
+ ```ts
103
+ const locale: Locale = href === "/pt" || href.startsWith("/pt/") ? "pt" : "en";
104
+ const path = locale === "pt" ? href.slice(3) || "/" : href;
105
+ const match = matchRoute(path, { routes });
106
+ ```
107
+
108
+ ## Automatic translation
109
+
110
+ Filling `fooPt` with an LLM (for example a CI job on the content change) is
111
+ possible. It needs an API key and a human review step. Start with manual
112
+ fields; add translation only when the team asks for it.
@@ -0,0 +1,79 @@
1
+ # Inventory: what is content, what is interface
2
+
3
+ Do this before writing any block. It decides the size of every PR after it.
4
+
5
+ ## Find the candidates
6
+
7
+ Search every component for:
8
+
9
+ - literal text in JSX (headings, paragraphs, button labels);
10
+ - arrays of links or cards (`const LINKS = [...]`, `const FEATURES = [...]`);
11
+ - copy objects (`COPY = { en: {...}, pt: {...} }`, `t.title`, `label`/`labelPt`);
12
+ - image URLs and `alt` texts written in code;
13
+ - page composition: a route component that renders `<Hero/><Features/><Faq/>`
14
+ in a fixed order.
15
+
16
+ A quick start:
17
+
18
+ ```sh
19
+ rg -n -g '*.tsx' '>[A-Z][a-z]+ [a-z]+' src/ # literal text in JSX
20
+ rg -n 'const [A-Z_]+ = \[' src/ # hardcoded lists
21
+ rg -n '(en|pt|es):\s*\{' src/ # per-language copy objects
22
+ ```
23
+
24
+ ## Classify each one
25
+
26
+ | Goes to the CMS (content) | Stays in code (interface or logic) |
27
+ |---|---|
28
+ | Headings, intros, card texts, calls to action and their links | `aria-label`s, "Skip to content", "Open menu" |
29
+ | Menus, footers, banners | Button states ("Copy link" then "Link copied") |
30
+ | Lists editors will reorder (cards, steps, FAQs) | Text tied to logic: status labels driven by data, version pickers |
31
+ | Which sections a page has, and their order | Navigation built by code from several sources |
32
+ | Images and their `alt` text | Error messages from forms and APIs |
33
+
34
+ Rule of thumb: if changing it needs a code release anyway (a new route, a new
35
+ version), it stays in code. Putting it in the CMS only adds a second place to
36
+ forget.
37
+
38
+ Interface text that stays in code still needs a translation when the site has
39
+ two languages. Keep it in a small dictionary in code, not in a block.
40
+
41
+ ## Record it
42
+
43
+ Write the inventory down before converting. One row per area:
44
+
45
+ | Area | Files | Fields | Shape | Priority |
46
+ |---|---|---|---|---|
47
+ | Header menu | `src/components/Header.tsx` | links (label, href) | global block | 1 |
48
+ | Home | `src/routes/index.tsx`, `src/components/home/*` | hero, guides, CTA | composed page | 2 |
49
+ | Landing pages | `src/routes/solutions/*` | hero, features | composed page | 3 |
50
+ | Articles | `content/*.mdx` | title, body, date | collection | 4 |
51
+
52
+ The shapes are explained in [content-shapes.md](./content-shapes.md).
53
+
54
+ Convert by priority: the most viewed pages first. They pay back the work
55
+ soonest, and the parity checks on them catch the most.
56
+
57
+ ## Size of a PR
58
+
59
+ One area per PR. A PR that converts the header, the home and two landings at
60
+ once cannot be checked for parity in a review: any pixel difference has four
61
+ possible causes.
62
+
63
+ Each PR carries:
64
+
65
+ - the block types added to the block map and the regenerated
66
+ `.deco/schema.gen.json`;
67
+ - the seeded `.deco/blocks` files, or the draft name they were pushed to (see
68
+ [seeding-content.md](./seeding-content.md));
69
+ - the parity evidence (see [pixel-parity.md](./pixel-parity.md)).
70
+
71
+ ## Clean up on the way
72
+
73
+ - Delete dead components you find. They cost nothing in Studio on v8 (only the
74
+ block map is listed), but they confuse the next person who greps for a text.
75
+ - When you move a component to a new file, say so in the PR description: open
76
+ PRs that import the old path will break.
77
+ - Element ids built from a list index (`card-0`) instead of a slug change the
78
+ HTML when an editor reorders the list. Check that no CSS or anchor link
79
+ targets them.
@@ -0,0 +1,175 @@
1
+ # Proving nothing changed
2
+
3
+ Every conversion PR is checked three ways before merge: the HTML, the pixels,
4
+ and a live edit. A PR built from a Figma file is compared with the design
5
+ instead of with `main`.
6
+
7
+ ## Two servers side by side
8
+
9
+ Run `main` and the branch at once. A separate worktree keeps `main` untouched:
10
+
11
+ ```sh
12
+ git worktree add ../site-main origin/main
13
+ (cd ../site-main && bun install --frozen-lockfile && npx vite dev --port 5192) &
14
+ npx vite dev --port 5191 &
15
+ ```
16
+
17
+ On a hosted site the branch reads its new blocks from a draft (see
18
+ [seeding-content.md](./seeding-content.md#a-hosted-site-site-set)). Add the
19
+ `__draft` value from `deco drafts url <name>` to every branch URL
20
+ (`?__draft=…`). Three things to know about draft pages on a site whose
21
+ document is `DecoDocument` (`@decocms/tanstack/react`):
22
+
23
+ - Once hydrated, a draft page shows a badge, fixed at the bottom left
24
+ (`[data-deco-preview-badge]`). Hide it before taking screenshots.
25
+ - If the link names a draft that cannot be read (deleted, or its host
26
+ failing), the page renders the release and shows a notice
27
+ (`[data-deco-preview-unavailable]`) instead of the badge.
28
+ - If the host is not allowed to preview, the page renders the release with
29
+ no badge and no notice (see "Draft hosts" in the `@decocms/tanstack`
30
+ README). So check that the badge is there: without it, the screenshot
31
+ compared the wrong content.
32
+
33
+ ## HTML parity
34
+
35
+ Strip what is expected to differ (scripts and comments) and diff the rest.
36
+ The draft badge mounts in the browser after hydration, so it is not in the
37
+ server HTML:
38
+
39
+ ```python
40
+ # body.py: normalize a page for diffing. Usage: curl -s URL | python3 body.py
41
+ import re, sys
42
+ s = sys.stdin.read()
43
+ t = re.search(r"<title>(.*?)</title>", s, flags=re.S)
44
+ print("TITLE", t.group(1) if t else None)
45
+ b = s[s.find("<body"):]
46
+ b = re.sub(r"<script.*?</script>", "", b, flags=re.S)
47
+ b = re.sub(r"<!--.*?-->", "", b, flags=re.S) # also React's streaming markers
48
+ print(b.replace("><", ">\n<"))
49
+ ```
50
+
51
+ ```sh
52
+ for p in / /pt /pricing /pt/pricing /docs/some-article; do
53
+ f=$(echo "$p" | tr / _)
54
+ curl -s "localhost:5192$p" | python3 body.py > "/tmp/main$f"
55
+ curl -s "localhost:5191$p?__draft=$DRAFT" | python3 body.py > "/tmp/new$f"
56
+ echo "$p: $(diff "/tmp/main$f" "/tmp/new$f" | grep -c '^[<>]') changed lines"
57
+ done
58
+ ```
59
+
60
+ Zero changed lines is the goal. The site writes the loop that renders
61
+ sections, so it controls the markup: if a wrapper element appears, remove it
62
+ rather than accept it.
63
+
64
+ Include a few pages you did **not** convert but whose components you moved or
65
+ touched. They must be identical too.
66
+
67
+ ## Pixel parity
68
+
69
+ Full-page screenshots of each page, in each language, at desktop and mobile
70
+ widths, on both servers, then a per-pixel diff.
71
+
72
+ Headless Chrome's `--screenshot` flag can hang on a Vite dev server (the HMR
73
+ socket never goes idle). `playwright-core` with a local Chromium works:
74
+
75
+ ```js
76
+ // shot.mjs: npm i playwright-core in a scratch folder; CHROMIUM=path to a Chromium binary
77
+ import { chromium } from "playwright-core";
78
+ const DRAFT = process.env.DRAFT ? `?__draft=${process.env.DRAFT}` : "";
79
+ const browser = await chromium.launch({ executablePath: process.env.CHROMIUM });
80
+ for (const [w, h] of [[1440, 900], [390, 844]])
81
+ for (const [name, port, query] of [["main", 5192, ""], ["new", 5191, DRAFT]])
82
+ for (const path of ["/", "/pt", "/pricing"]) {
83
+ const page = await browser.newPage({ viewport: { width: w, height: h } });
84
+ page.on("pageerror", (e) => console.error(name, path, String(e)));
85
+ await page.goto(`http://localhost:${port}${path}${query}`, { waitUntil: "load" });
86
+ // The badge mounts after hydration; no badge means the release rendered, not the draft.
87
+ if (query) await page.waitForSelector("[data-deco-preview-badge]", { timeout: 10_000 });
88
+ await page.addStyleTag({ content: "[data-deco-preview-badge]{display:none!important}" });
89
+ // Scroll once so reveal-on-scroll animations and lazy images run.
90
+ await page.evaluate(async () => {
91
+ for (let y = 0; y < document.body.scrollHeight; y += 400) { scrollTo(0, y); await new Promise((r) => setTimeout(r, 50)); }
92
+ scrollTo(0, 0);
93
+ });
94
+ await page.waitForLoadState("networkidle").catch(() => {});
95
+ await page.waitForTimeout(700);
96
+ await page.screenshot({ path: `shots/${name}${path.replaceAll("/", "_")}-${w}.png`, fullPage: true });
97
+ await page.close();
98
+ }
99
+ await browser.close();
100
+ ```
101
+
102
+ ```python
103
+ # diff.py: pip install pillow
104
+ from PIL import Image, ImageChops
105
+ import glob
106
+ for m in sorted(glob.glob("shots/main*.png")):
107
+ n = m.replace("main", "new", 1)
108
+ a, b = Image.open(m).convert("L"), Image.open(n).convert("L")
109
+ if a.size != b.size: print(m, "SIZE", a.size, b.size); continue
110
+ d = ImageChops.difference(a, b); px = [p for p in d.getdata() if p]
111
+ print(m, "identical" if not px else f"{len(px)} px, max {max(px)}/255 in {d.getbbox()}")
112
+ ```
113
+
114
+ Reading the result:
115
+
116
+ - A different page height, or any visible difference, is a regression.
117
+ - In a real conversion, a few dozen pixels at an intensity of 7/255 or less,
118
+ around a transition (a select chevron, an animated demo), were rendering
119
+ noise. Crop that box from both images and look before dismissing it.
120
+ - Sections that stream in (a `Suspense` boundary per section) can be caught
121
+ half-rendered. If one run shows a fallback, wait for it to go away
122
+ (`page.waitForSelector`) instead of raising the timeout everywhere.
123
+
124
+ ## Against a Figma design
125
+
126
+ With no `main` to compare with, the baseline is the design:
127
+
128
+ 1. Call `get_screenshot` on each section frame (desktop and mobile). Save as
129
+ `tests/visual-qa/baselines/<device>/<order>-<Section>.png`.
130
+ 2. Screenshot each section of the page at the frame's width (1440 and 375 are
131
+ common). If the site renders an attribute per section, use it as a
132
+ locator; otherwise screenshot by section element order.
133
+ 3. Compare by eye and list each mismatch. A pixel diff against a Figma render
134
+ is noisy (font rendering, antialiasing); it finds regions, it does not
135
+ judge them.
136
+
137
+ What to compare, per section:
138
+
139
+ - **Layout:** direction, alignment, grid columns, max width and centering,
140
+ order of elements.
141
+ - **Spacing:** padding, gaps, vertical rhythm between sections.
142
+ - **Type:** family, size, weight, line height, letter spacing, case, color.
143
+ - **Color:** backgrounds, borders, buttons, links, hover states.
144
+ - **Images:** the right asset, aspect ratio, crop (`object-fit`), radius.
145
+ - **Responsive:** both widths, and no jump at the breakpoints in between
146
+ (768px, 1024px).
147
+
148
+ Write the mismatches as a table and fix them one by one:
149
+
150
+ | # | Device | Section | Issue | Expected | Actual | Fix |
151
+ |---|---|---|---|---|---|---|
152
+ | 1 | desktop | Hero | title size | 48px | 36px | use the `display` text token |
153
+ | 2 | mobile | Header | menu icon missing | present | missing | render the menu button below `md` |
154
+
155
+ Re-screenshot after each fix and mark the row fixed. Done means every row is
156
+ fixed at both widths.
157
+
158
+ ## Live edit
159
+
160
+ With the branch running, change the content and watch it land:
161
+
162
+ - change a text in each language and confirm it changes on that language's
163
+ pages only;
164
+ - empty a `fooPt` and confirm the secondary language falls back to `foo`;
165
+ - remove and reorder sections of a page and confirm the rendered order follows;
166
+ - break a required field and confirm `deco check` names it (`deco check
167
+ --draft=<name>` on a hosted site: without a flag it checks production).
168
+
169
+ With content in git, edit the block files (`deco content --watch` reloads the
170
+ page). On a hosted site, make the same edits in the draft, from Studio or with
171
+ `deco push --draft=<name>`. Restore the content afterwards.
172
+
173
+ Then the real path, end to end: open the page in Studio, edit, preview, and
174
+ publish (with the owner's OK) or discard the draft. Confirm the change on the
175
+ site. This is the half of the goal that the pixel checks do not prove.
@@ -0,0 +1,119 @@
1
+ # Seeding content from the current code
2
+
3
+ Never retype content. Extract it from the code that ships today. Byte-identical
4
+ content is what makes the [pixel comparison](./pixel-parity.md) mean
5
+ something: if a single apostrophe changed, you cannot tell a typo from a
6
+ regression.
7
+
8
+ ## Extract with a throwaway script
9
+
10
+ Most hardcoded content is already data: a `COPY` object, a `LINKS` array. Load
11
+ it in isolation and write the block JSON from it.
12
+
13
+ ```ts
14
+ // scripts/seed-header.ts (run once with `bun scripts/seed-header.ts`, then delete)
15
+ import fs from "node:fs";
16
+ import { LINKS } from "../src/components/Header.constants";
17
+
18
+ const block = {
19
+ __resolveType: "header-menu",
20
+ links: LINKS.map(({ label, labelPt, href }) => ({ label, labelPt, href })),
21
+ };
22
+ const name = "Header menu";
23
+ fs.writeFileSync(`.deco/blocks/${encodeURIComponent(name)}.json`, `${JSON.stringify(block, null, 2)}\n`);
24
+ ```
25
+
26
+ - If the constant lives in a component file that imports React or CSS, move it
27
+ to its own module first (the component then imports it). That is a
28
+ refactor with no visual change; commit it separately.
29
+ - Component references in the data (`icon: RocketIcon`) cannot go into JSON.
30
+ Replace them with string keys and keep a closed list in code:
31
+ `const ICONS = { rocket: RocketIcon, book: BookIcon }`, with
32
+ `icon: keyof typeof ICONS` in `Props`. Editors then pick from a list instead
33
+ of typing a free-text name. `deco-cms-schema` shows how the form renders it.
34
+ - Text written straight in JSX has no constant to load. Copy it with the
35
+ script anyway (read the file, cut the strings), or paste it once and check
36
+ the [HTML diff](./pixel-parity.md#html-parity) shows no change.
37
+ - Once the block exists, delete the constant. Keeping it "as a fallback"
38
+ creates a second source of truth.
39
+
40
+ The file name is `encodeURIComponent(name)` plus `.json`, directly in
41
+ `.deco/blocks` (subfolders are not read).
42
+
43
+ ## Content in git (no `site`)
44
+
45
+ A site created with `createCMS({ blocks, content })` and no `site` reads the
46
+ content module, `.deco/blocks.gen.ts`, bundled with the build.
47
+
48
+ ```sh
49
+ deco schema # .deco/index.ts → .deco/schema.gen.json
50
+ deco content # .deco/blocks → .deco/blocks.gen.ts
51
+ deco check # every saved block against the schema (no DECO_SITE set)
52
+ ```
53
+
54
+ During `vite dev`, `deco content --watch` rewrites the module on each save,
55
+ and the `decoContent()` plugin (included in `decoTanstack()`) swaps the new
56
+ content into the running CMS and reloads open pages. Edit a block file, and
57
+ the page shows it.
58
+
59
+ ## A hosted site (`site` set)
60
+
61
+ A site created with `createCMS({ blocks, site })` reads its content from the
62
+ delivery CDN at runtime. The CLI finds the same site in `DECO_SITE` (the
63
+ environment, `.env`, `.dev.vars` or `vars` in the wrangler config). The local
64
+ `.deco/blocks` is what `deco pull` wrote, and changes travel as drafts:
65
+
66
+ ```sh
67
+ deco pull # production into .deco/blocks
68
+ # write or edit the seeded files
69
+ deco diff # what changed since the pull
70
+ deco push --draft=header-menu # one save into the draft (creates it); prints its preview link
71
+ deco check --draft=header-menu # the draft against the local .deco/schema.gen.json
72
+ deco drafts url header-menu # the preview link again
73
+ ```
74
+
75
+ - `deco push` sends only the blocks changed since the pull. Deletes are sent
76
+ only with `--prune`.
77
+ - One push is one save, at most 500 blocks and 8 MiB. A larger push fails with
78
+ "don't fit one save": push fewer blocks at a time.
79
+ - `deco check --draft` validates the draft against the schema on disk, so it
80
+ checks the branch's new types before anything is deployed.
81
+ - Open the preview link on a local dev server of the branch to see the seeded
82
+ content with the new code. A draft page shows a "Preview mode" badge. With
83
+ no badge, the page rendered the release: either the host is not allowed to
84
+ preview (no notice; see "Draft hosts" in the `@decocms/tanstack` README, and
85
+ `deco-site-workflow`), or the draft could not be read (a notice says so).
86
+
87
+ The full set of content commands (`drafts`, `publish`, `releases`, rollback)
88
+ is in `deco-site-workflow`.
89
+
90
+ ## Order of publish and deploy
91
+
92
+ On a hosted site, content and code ship separately. Pick the order so that the
93
+ live site never runs code that reads a block that is not published yet:
94
+
95
+ 1. Publish the draft with the **new** blocks first. Old code never reads them,
96
+ so this changes nothing on the live site.
97
+ 2. Deploy the code that reads them. The production deploy should also run
98
+ `deco schema push` (see `deco-site-workflow`): that is what gives Studio
99
+ the forms for the new types.
100
+ 3. Only then publish changes to **existing** blocks that the old code would
101
+ not understand, such as a page whose sections now use a new section type.
102
+
103
+ Do not run `deco publish` without the site owner's explicit OK for that
104
+ publish.
105
+
106
+ ## What `deco check` covers
107
+
108
+ `deco check` validates each saved block against the generated schema:
109
+
110
+ - required fields that are missing, unknown fields, wrong types, values
111
+ outside an `@options` list;
112
+ - a `__resolveType` that names no block type, built-in or saved block;
113
+ - a block placed in a field it does not fit;
114
+ - page paths that conflict, and redirect rules outside the redirects block.
115
+
116
+ It does not check that an internal link (`href: "/pricing"`) points at a page
117
+ that exists, and an empty string passes a required string field. If either
118
+ matters for your site, add a small script to CI that walks `.deco/blocks` for
119
+ link fields and compares them with the page paths and the site's own routes.
@@ -0,0 +1,74 @@
1
+ ---
2
+ name: deco-nextjs-site
3
+ description: "Wiring a Next.js App Router site to @decocms/nextjs 8 (with @decocms/blocks 8, Next 16, React 19): the block map in .deco/index.tsx and the two createCMS handles, withDeco in next.config, the proxy (@decocms/nextjs/proxy: decideDraft, decideVisitor, decideAssignments, the /_draft and /_assignments rewrites, or draftProxy), reading and rendering resolved pages in Server Components (@decocms/nextjs/server: bindDraft, contentClient, assignedClient; matchRoute, redirects, notFound), page metadata from the page's seo block, ISR caching on the assignments route (revalidate = 600, never force-static, assignmentsKey for a CDN), the Studio bridge (StudioBridge, StudioPage, withStudioCsp), the next/image loader (@decocms/nextjs/image-loader) and the request metric (@decocms/nextjs/instrumentation). Load it for any v8 site built on Next.js: scaffolding, a draft that does not show, a page that renders on every request instead of caching, Studio not driving the page, or wrong metadata."
4
+ ---
5
+
6
+ # Deco on Next.js (v8)
7
+
8
+ `@decocms/nextjs` 8 is a set of small helpers a Next.js App Router site calls
9
+ from its own `proxy.ts`, layouts, pages and `next.config`. It makes no hosting
10
+ assumption: no CDN, no platform rules. Content comes from `@decocms/blocks`
11
+ (`createCMS`, `client.resolve`, `matchRoute`); this package adds draft
12
+ previews, tests and campaigns decided once per request, Next's cache, and the
13
+ Studio bridge.
14
+
15
+ Load the reference for the job in front of you. Every name below exists in
16
+ `packages/nextjs/src` or `packages/blocks/src/v8`. The full working app is
17
+ `examples/nextjs-binding-smoke` in this repository: when this skill and that
18
+ example disagree, the example wins.
19
+
20
+ ## When to load what
21
+
22
+ | Reference | Load it when |
23
+ |---|---|
24
+ | [`references/setup.md`](./references/setup.md) | Starting a site or adding Deco to a Next app: packages, file layout, the block map, the two CMS handles, `withDeco`, scripts, the image loader, the request metric |
25
+ | [`references/proxy-and-drafts.md`](./references/proxy-and-drafts.md) | Writing `proxy.ts`; a Studio draft link shows the published page; preview hosts; the draft route and `bindDraft`; the preview badge |
26
+ | [`references/rendering.md`](./references/rendering.md) | Reading and rendering a page in a Server Component: routes, redirects, `resolve`, sections, client components, errors |
27
+ | [`references/metadata-seo.md`](./references/metadata-seo.md) | `<title>` or description wrong or missing; the `seo` block; noindex on drafts |
28
+ | [`references/caching.md`](./references/caching.md) | ISR, the assignments route, a page that renders on every request, a CDN in front, stale content after publish |
29
+ | [`references/studio-bridge.md`](./references/studio-bridge.md) | Studio cannot select or reload sections, "." opens the wrong page, CSP blocks Studio, a local Studio |
30
+
31
+ ## The shape of a request
32
+
33
+ 1. `proxy.ts` decides once: the version (a Studio link's draft or old
34
+ release, on an allowed host), the visitor (`deco_segment` cookie) and every
35
+ test and campaign on or off.
36
+ 2. A published CMS page is rewritten to `/_assignments/<segment>/<path>`. The
37
+ page reads no request, so Next caches it (ISR).
38
+ 3. A preview request is rewritten to `/_draft/<path>`. That route is dynamic,
39
+ binds the draft with `bindDraft`, and is never cached.
40
+ 4. Both routes build one content client, match the path, follow redirects,
41
+ resolve the page and render its sections.
42
+
43
+ ## Rules that are easy to break
44
+
45
+ - The route folders are `app/%5Fdraft/...` and `app/%5Fassignments/...`. A
46
+ folder named `_draft` is private in Next and never routes.
47
+ - Never call `bindDraft`, `headers()`, `cookies()` or `searchParams` on the
48
+ assignments route or in the root layout. Any of them makes Next render the
49
+ page on every request.
50
+ - Never `export const dynamic = "force-static"` on a CMS page. Use
51
+ `revalidate`.
52
+ - The proxy imports a CMS handle with an empty block map
53
+ (`createCMS({ blocks: {}, ...cmsConfig })`), so no section reaches the proxy
54
+ bundle.
55
+ - Never edit generated files (`.deco/schema.gen.json`, `.deco/blocks.gen.ts`).
56
+ Change the types or the content and run the CLI again.
57
+
58
+ ## Not in v8
59
+
60
+ v7's `createNextSetup`, `createDecoRouteHandlers`, `createDecoPreviewPage`,
61
+ the `/setup` and `/routeHandlers` subpaths, `src/sections/*` shims as block
62
+ keys, `generate:deco` and the `/deco/*` admin routes do not exist in
63
+ `@decocms/nextjs` 8. Moving a v7 site: load `deco-v7-to-v8-migration`.
64
+
65
+ ## Related skills
66
+
67
+ - `deco-site-workflow`: the `deco` CLI (`schema`, `schema push`, `check`,
68
+ `pull`, `push --draft`, `publish`) and how releases reach the site.
69
+ - `deco-site-authoring`: writing sections, pages and loaders.
70
+ - `deco-cms-schema`: how a Props type becomes the Studio form.
71
+ - `deco-variants`: multivariate blocks, tests and campaigns.
72
+ - `deco-images-media`: image providers, quality and LCP.
73
+ - `deco-storefront-caching`: cache keys and egress, with the Next equivalents.
74
+ - `deco-tanstack-site`: the same wiring on TanStack Start.