@decocms/blocks 8.10.0 → 8.11.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.
- package/dist/v8/cli/index.d.ts +1 -0
- package/dist/v8/cli/index.d.ts.map +1 -1
- package/dist/v8/cli/index.js +1 -0
- package/dist/v8/cli/index.js.map +1 -1
- package/dist/v8/cli/run.d.ts +2 -0
- package/dist/v8/cli/run.d.ts.map +1 -1
- package/dist/v8/cli/run.js +30 -1
- package/dist/v8/cli/run.js.map +1 -1
- package/dist/v8/cli/skills.d.ts +25 -0
- package/dist/v8/cli/skills.d.ts.map +1 -0
- package/dist/v8/cli/skills.js +70 -0
- package/dist/v8/cli/skills.js.map +1 -0
- package/package.json +3 -2
- package/skills/deco-apps/SKILL.md +82 -0
- package/skills/deco-apps/references/algolia.md +51 -0
- package/skills/deco-apps/references/commerce-types.md +132 -0
- package/skills/deco-apps/references/instrumented-fetch.md +144 -0
- package/skills/deco-apps/references/magento.md +55 -0
- package/skills/deco-apps/references/messaging.md +76 -0
- package/skills/deco-apps/references/shopify.md +69 -0
- package/skills/deco-apps/references/vendored-loaders.md +135 -0
- package/skills/deco-apps/references/vtex-cookies-auth.md +146 -0
- package/skills/deco-apps/references/vtex.md +150 -0
- package/skills/deco-apps/references/wake.md +75 -0
- package/skills/deco-cms-schema/SKILL.md +80 -0
- package/skills/deco-cms-schema/references/annotations.md +147 -0
- package/skills/deco-cms-schema/references/content-hygiene.md +91 -0
- package/skills/deco-cms-schema/references/formats-and-widgets.md +112 -0
- package/skills/deco-cms-schema/references/shapes-that-break-the-form.md +165 -0
- package/skills/deco-cms-schema/references/types-to-fields.md +112 -0
- package/skills/deco-go-live/SKILL.md +127 -0
- package/skills/deco-go-live/references/content-releases.md +90 -0
- package/skills/deco-go-live/references/process.md +106 -0
- package/skills/deco-go-live/references/proxy-headers-checkout.md +139 -0
- package/skills/deco-go-live/references/qa-checklist-template.md +150 -0
- package/skills/deco-go-live/references/qa-inventory.md +120 -0
- package/skills/deco-go-live/references/react-spa.md +183 -0
- package/skills/deco-go-live/references/seo-analytics.md +114 -0
- package/skills/deco-go-live/references/traffic-ramp.md +87 -0
- package/skills/deco-go-live/references/worker-runtime.md +93 -0
- package/skills/deco-go-live/scripts/preflight.sh +221 -0
- package/skills/deco-images-media/SKILL.md +64 -0
- package/skills/deco-images-media/references/asset-upload.md +191 -0
- package/skills/deco-images-media/references/components-per-binding.md +167 -0
- package/skills/deco-images-media/references/providers-and-cdn.md +145 -0
- package/skills/deco-images-media/references/quality-and-lcp.md +93 -0
- package/skills/deco-images-media/references/troubleshooting.md +147 -0
- package/skills/deco-images-media/references/video.md +122 -0
- package/skills/deco-make-editable/SKILL.md +94 -0
- package/skills/deco-make-editable/references/a11y-and-e2e.md +104 -0
- package/skills/deco-make-editable/references/content-shapes.md +198 -0
- package/skills/deco-make-editable/references/from-figma.md +110 -0
- package/skills/deco-make-editable/references/i18n-fields.md +112 -0
- package/skills/deco-make-editable/references/inventory.md +79 -0
- package/skills/deco-make-editable/references/pixel-parity.md +175 -0
- package/skills/deco-make-editable/references/seeding-content.md +119 -0
- package/skills/deco-nextjs-site/SKILL.md +74 -0
- package/skills/deco-nextjs-site/references/caching.md +116 -0
- package/skills/deco-nextjs-site/references/metadata-seo.md +100 -0
- package/skills/deco-nextjs-site/references/proxy-and-drafts.md +177 -0
- package/skills/deco-nextjs-site/references/rendering.md +171 -0
- package/skills/deco-nextjs-site/references/setup.md +190 -0
- package/skills/deco-nextjs-site/references/studio-bridge.md +130 -0
- package/skills/deco-site-authoring/SKILL.md +75 -0
- package/skills/deco-site-authoring/references/lazy-blocks.md +155 -0
- package/skills/deco-site-authoring/references/loaders.md +192 -0
- package/skills/deco-site-authoring/references/pages.md +156 -0
- package/skills/deco-site-authoring/references/review-before-publish.md +95 -0
- package/skills/deco-site-authoring/references/sections.md +158 -0
- package/skills/deco-site-authoring/references/seo.md +116 -0
- package/skills/deco-site-workflow/SKILL.md +92 -0
- package/skills/deco-site-workflow/references/check.md +116 -0
- package/skills/deco-site-workflow/references/cli-reference.md +104 -0
- package/skills/deco-site-workflow/references/content-layout.md +93 -0
- package/skills/deco-site-workflow/references/content-sync.md +146 -0
- package/skills/deco-site-workflow/references/delivery.md +51 -0
- package/skills/deco-site-workflow/references/deploy.md +87 -0
- package/skills/deco-site-workflow/references/schema.md +173 -0
- package/skills/deco-site-workflow/references/serve-and-studio.md +138 -0
- package/skills/deco-storefront-caching/SKILL.md +67 -0
- package/skills/deco-storefront-caching/references/cache-keys.md +129 -0
- package/skills/deco-storefront-caching/references/case-study.md +82 -0
- package/skills/deco-storefront-caching/references/egress-traps.md +153 -0
- package/skills/deco-storefront-caching/references/nextjs.md +60 -0
- package/skills/deco-storefront-caching/references/perf-guardrails-e2e.md +123 -0
- package/skills/deco-storefront-caching/references/verification.md +136 -0
- package/skills/deco-storefront-caching/references/worker-page-cache.md +160 -0
- package/skills/deco-storefront-caching/scripts/html-anatomy.mjs +97 -0
- package/skills/deco-storefront-performance/SKILL.md +81 -0
- package/skills/deco-storefront-performance/references/cls-third-party.md +90 -0
- package/skills/deco-storefront-performance/references/hydration.md +116 -0
- package/skills/deco-storefront-performance/references/loaders-n-plus-1.md +107 -0
- package/skills/deco-storefront-performance/references/navigation-ux.md +130 -0
- package/skills/deco-storefront-performance/references/payload-trim.md +163 -0
- package/skills/deco-storefront-performance/references/render-location.md +152 -0
- package/skills/deco-storefront-performance/references/request-dedupe.md +147 -0
- package/skills/deco-storefront-performance/references/trace-reading.md +79 -0
- package/skills/deco-storefront-performance/references/worker-memory.md +176 -0
- package/skills/deco-tanstack-site/SKILL.md +68 -0
- package/skills/deco-tanstack-site/references/document-and-security.md +155 -0
- package/skills/deco-tanstack-site/references/router-and-navigation.md +137 -0
- package/skills/deco-tanstack-site/references/routes-and-pages.md +183 -0
- package/skills/deco-tanstack-site/references/server-functions.md +123 -0
- package/skills/deco-tanstack-site/references/setup.md +153 -0
- package/skills/deco-tanstack-site/references/worker-entry.md +152 -0
- package/skills/deco-v7-to-v8-migration/SKILL.md +122 -0
- package/skills/deco-v7-to-v8-migration/references/caching-and-privacy.md +10 -0
- package/skills/deco-v7-to-v8-migration/references/content.md +25 -0
- package/skills/deco-v7-to-v8-migration/references/editor-forms.md +27 -0
- package/skills/deco-v7-to-v8-migration/references/faststore.md +40 -0
- package/skills/deco-v7-to-v8-migration/references/framework-code.md +53 -0
- package/skills/deco-v7-to-v8-migration/references/hosted-releases.md +16 -0
- package/skills/deco-v7-to-v8-migration/references/import-map.md +81 -0
- package/skills/deco-v7-to-v8-migration/references/legacy-names.md +33 -0
- package/skills/deco-v7-to-v8-migration/references/manual-steps.md +10 -0
- package/skills/deco-v7-to-v8-migration/references/native-apps.md +43 -0
- package/skills/deco-v7-to-v8-migration/references/nextjs.md +19 -0
- package/skills/deco-v7-to-v8-migration/references/parity.md +66 -0
- package/skills/deco-v7-to-v8-migration/references/rendering.md +13 -0
- package/skills/deco-v7-to-v8-migration/references/running-the-script.md +29 -0
- package/skills/deco-v7-to-v8-migration/references/script-steps.md +13 -0
- package/skills/deco-v7-to-v8-migration/references/server-functions.md +15 -0
- package/skills/deco-v7-to-v8-migration/references/sibling-port.md +11 -0
- package/skills/deco-v7-to-v8-migration/references/site-code.md +15 -0
- package/skills/deco-v7-to-v8-migration/references/telemetry.md +10 -0
- package/skills/deco-v7-to-v8-migration/references/verify.md +20 -0
- package/skills/deco-v7-to-v8-migration/scripts/apps.ts +297 -0
- package/skills/deco-v7-to-v8-migration/scripts/asyncRendering.ts +73 -0
- package/skills/deco-v7-to-v8-migration/scripts/blockMap.ts +584 -0
- package/skills/deco-v7-to-v8-migration/scripts/ciSchemaCheck.ts +145 -0
- package/skills/deco-v7-to-v8-migration/scripts/compat.ts +357 -0
- package/skills/deco-v7-to-v8-migration/scripts/content.ts +121 -0
- package/skills/deco-v7-to-v8-migration/scripts/experiments.ts +81 -0
- package/skills/deco-v7-to-v8-migration/scripts/framework.ts +61 -0
- package/skills/deco-v7-to-v8-migration/scripts/imageCopy.ts +276 -0
- package/skills/deco-v7-to-v8-migration/scripts/imageModule.ts +285 -0
- package/skills/deco-v7-to-v8-migration/scripts/imports.ts +942 -0
- package/skills/deco-v7-to-v8-migration/scripts/invoke.ts +624 -0
- package/skills/deco-v7-to-v8-migration/scripts/legacyNames.ts +45 -0
- package/skills/deco-v7-to-v8-migration/scripts/main.ts +59 -0
- package/skills/deco-v7-to-v8-migration/scripts/matchers.ts +41 -0
- package/skills/deco-v7-to-v8-migration/scripts/migrate.ts +176 -0
- package/skills/deco-v7-to-v8-migration/scripts/redirects.ts +455 -0
- package/skills/deco-v7-to-v8-migration/scripts/report.ts +50 -0
- package/skills/deco-v7-to-v8-migration/scripts/scaffold.ts +1119 -0
- package/skills/deco-v7-to-v8-migration/scripts/secrets.ts +35 -0
- package/skills/deco-v7-to-v8-migration/scripts/sectionLoaders.ts +216 -0
- package/skills/deco-v7-to-v8-migration/scripts/siteSettings.ts +261 -0
- package/skills/deco-v7-to-v8-migration/scripts/stubs.ts +388 -0
- package/skills/deco-v7-to-v8-migration/scripts/tsconfig.json +7 -0
- package/skills/deco-v7-to-v8-migration/scripts/vendor.ts +249 -0
- package/skills/deco-v7-to-v8-migration/scripts/vtexInvoke.ts +240 -0
- package/skills/deco-v7-to-v8-migration/scripts/walk.ts +30 -0
- package/skills/deco-variants/SKILL.md +57 -0
- package/skills/deco-variants/references/caching-variants.md +63 -0
- package/skills/deco-variants/references/custom-matchers.md +83 -0
- package/skills/deco-variants/references/draft-preview.md +59 -0
- package/skills/deco-variants/references/experiments-and-campaigns.md +104 -0
- package/skills/deco-variants/references/multivariate.md +85 -0
- package/skills/deco-variants/references/v7-matchers.md +71 -0
- package/src/v8/cli/index.ts +1 -0
- package/src/v8/cli/run.ts +35 -1
- package/src/v8/cli/skills.ts +91 -0
|
@@ -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.
|