@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.
Files changed (163) hide show
  1. package/dist/v8/cli/index.d.ts +1 -0
  2. package/dist/v8/cli/index.d.ts.map +1 -1
  3. package/dist/v8/cli/index.js +1 -0
  4. package/dist/v8/cli/index.js.map +1 -1
  5. package/dist/v8/cli/run.d.ts +2 -0
  6. package/dist/v8/cli/run.d.ts.map +1 -1
  7. package/dist/v8/cli/run.js +30 -1
  8. package/dist/v8/cli/run.js.map +1 -1
  9. package/dist/v8/cli/skills.d.ts +25 -0
  10. package/dist/v8/cli/skills.d.ts.map +1 -0
  11. package/dist/v8/cli/skills.js +70 -0
  12. package/dist/v8/cli/skills.js.map +1 -0
  13. package/package.json +3 -2
  14. package/skills/deco-apps/SKILL.md +82 -0
  15. package/skills/deco-apps/references/algolia.md +51 -0
  16. package/skills/deco-apps/references/commerce-types.md +132 -0
  17. package/skills/deco-apps/references/instrumented-fetch.md +144 -0
  18. package/skills/deco-apps/references/magento.md +55 -0
  19. package/skills/deco-apps/references/messaging.md +76 -0
  20. package/skills/deco-apps/references/shopify.md +69 -0
  21. package/skills/deco-apps/references/vendored-loaders.md +135 -0
  22. package/skills/deco-apps/references/vtex-cookies-auth.md +146 -0
  23. package/skills/deco-apps/references/vtex.md +150 -0
  24. package/skills/deco-apps/references/wake.md +75 -0
  25. package/skills/deco-cms-schema/SKILL.md +80 -0
  26. package/skills/deco-cms-schema/references/annotations.md +147 -0
  27. package/skills/deco-cms-schema/references/content-hygiene.md +91 -0
  28. package/skills/deco-cms-schema/references/formats-and-widgets.md +112 -0
  29. package/skills/deco-cms-schema/references/shapes-that-break-the-form.md +165 -0
  30. package/skills/deco-cms-schema/references/types-to-fields.md +112 -0
  31. package/skills/deco-go-live/SKILL.md +127 -0
  32. package/skills/deco-go-live/references/content-releases.md +90 -0
  33. package/skills/deco-go-live/references/process.md +106 -0
  34. package/skills/deco-go-live/references/proxy-headers-checkout.md +139 -0
  35. package/skills/deco-go-live/references/qa-checklist-template.md +150 -0
  36. package/skills/deco-go-live/references/qa-inventory.md +120 -0
  37. package/skills/deco-go-live/references/react-spa.md +183 -0
  38. package/skills/deco-go-live/references/seo-analytics.md +114 -0
  39. package/skills/deco-go-live/references/traffic-ramp.md +87 -0
  40. package/skills/deco-go-live/references/worker-runtime.md +93 -0
  41. package/skills/deco-go-live/scripts/preflight.sh +221 -0
  42. package/skills/deco-images-media/SKILL.md +64 -0
  43. package/skills/deco-images-media/references/asset-upload.md +191 -0
  44. package/skills/deco-images-media/references/components-per-binding.md +167 -0
  45. package/skills/deco-images-media/references/providers-and-cdn.md +145 -0
  46. package/skills/deco-images-media/references/quality-and-lcp.md +93 -0
  47. package/skills/deco-images-media/references/troubleshooting.md +147 -0
  48. package/skills/deco-images-media/references/video.md +122 -0
  49. package/skills/deco-make-editable/SKILL.md +94 -0
  50. package/skills/deco-make-editable/references/a11y-and-e2e.md +104 -0
  51. package/skills/deco-make-editable/references/content-shapes.md +198 -0
  52. package/skills/deco-make-editable/references/from-figma.md +110 -0
  53. package/skills/deco-make-editable/references/i18n-fields.md +112 -0
  54. package/skills/deco-make-editable/references/inventory.md +79 -0
  55. package/skills/deco-make-editable/references/pixel-parity.md +175 -0
  56. package/skills/deco-make-editable/references/seeding-content.md +119 -0
  57. package/skills/deco-nextjs-site/SKILL.md +74 -0
  58. package/skills/deco-nextjs-site/references/caching.md +116 -0
  59. package/skills/deco-nextjs-site/references/metadata-seo.md +100 -0
  60. package/skills/deco-nextjs-site/references/proxy-and-drafts.md +177 -0
  61. package/skills/deco-nextjs-site/references/rendering.md +171 -0
  62. package/skills/deco-nextjs-site/references/setup.md +190 -0
  63. package/skills/deco-nextjs-site/references/studio-bridge.md +130 -0
  64. package/skills/deco-site-authoring/SKILL.md +75 -0
  65. package/skills/deco-site-authoring/references/lazy-blocks.md +155 -0
  66. package/skills/deco-site-authoring/references/loaders.md +192 -0
  67. package/skills/deco-site-authoring/references/pages.md +156 -0
  68. package/skills/deco-site-authoring/references/review-before-publish.md +95 -0
  69. package/skills/deco-site-authoring/references/sections.md +158 -0
  70. package/skills/deco-site-authoring/references/seo.md +116 -0
  71. package/skills/deco-site-workflow/SKILL.md +92 -0
  72. package/skills/deco-site-workflow/references/check.md +116 -0
  73. package/skills/deco-site-workflow/references/cli-reference.md +104 -0
  74. package/skills/deco-site-workflow/references/content-layout.md +93 -0
  75. package/skills/deco-site-workflow/references/content-sync.md +146 -0
  76. package/skills/deco-site-workflow/references/delivery.md +51 -0
  77. package/skills/deco-site-workflow/references/deploy.md +87 -0
  78. package/skills/deco-site-workflow/references/schema.md +173 -0
  79. package/skills/deco-site-workflow/references/serve-and-studio.md +138 -0
  80. package/skills/deco-storefront-caching/SKILL.md +67 -0
  81. package/skills/deco-storefront-caching/references/cache-keys.md +129 -0
  82. package/skills/deco-storefront-caching/references/case-study.md +82 -0
  83. package/skills/deco-storefront-caching/references/egress-traps.md +153 -0
  84. package/skills/deco-storefront-caching/references/nextjs.md +60 -0
  85. package/skills/deco-storefront-caching/references/perf-guardrails-e2e.md +123 -0
  86. package/skills/deco-storefront-caching/references/verification.md +136 -0
  87. package/skills/deco-storefront-caching/references/worker-page-cache.md +160 -0
  88. package/skills/deco-storefront-caching/scripts/html-anatomy.mjs +97 -0
  89. package/skills/deco-storefront-performance/SKILL.md +81 -0
  90. package/skills/deco-storefront-performance/references/cls-third-party.md +90 -0
  91. package/skills/deco-storefront-performance/references/hydration.md +116 -0
  92. package/skills/deco-storefront-performance/references/loaders-n-plus-1.md +107 -0
  93. package/skills/deco-storefront-performance/references/navigation-ux.md +130 -0
  94. package/skills/deco-storefront-performance/references/payload-trim.md +163 -0
  95. package/skills/deco-storefront-performance/references/render-location.md +152 -0
  96. package/skills/deco-storefront-performance/references/request-dedupe.md +147 -0
  97. package/skills/deco-storefront-performance/references/trace-reading.md +79 -0
  98. package/skills/deco-storefront-performance/references/worker-memory.md +176 -0
  99. package/skills/deco-tanstack-site/SKILL.md +68 -0
  100. package/skills/deco-tanstack-site/references/document-and-security.md +155 -0
  101. package/skills/deco-tanstack-site/references/router-and-navigation.md +137 -0
  102. package/skills/deco-tanstack-site/references/routes-and-pages.md +183 -0
  103. package/skills/deco-tanstack-site/references/server-functions.md +123 -0
  104. package/skills/deco-tanstack-site/references/setup.md +153 -0
  105. package/skills/deco-tanstack-site/references/worker-entry.md +152 -0
  106. package/skills/deco-v7-to-v8-migration/SKILL.md +122 -0
  107. package/skills/deco-v7-to-v8-migration/references/caching-and-privacy.md +10 -0
  108. package/skills/deco-v7-to-v8-migration/references/content.md +25 -0
  109. package/skills/deco-v7-to-v8-migration/references/editor-forms.md +27 -0
  110. package/skills/deco-v7-to-v8-migration/references/faststore.md +40 -0
  111. package/skills/deco-v7-to-v8-migration/references/framework-code.md +53 -0
  112. package/skills/deco-v7-to-v8-migration/references/hosted-releases.md +16 -0
  113. package/skills/deco-v7-to-v8-migration/references/import-map.md +81 -0
  114. package/skills/deco-v7-to-v8-migration/references/legacy-names.md +33 -0
  115. package/skills/deco-v7-to-v8-migration/references/manual-steps.md +10 -0
  116. package/skills/deco-v7-to-v8-migration/references/native-apps.md +43 -0
  117. package/skills/deco-v7-to-v8-migration/references/nextjs.md +19 -0
  118. package/skills/deco-v7-to-v8-migration/references/parity.md +66 -0
  119. package/skills/deco-v7-to-v8-migration/references/rendering.md +13 -0
  120. package/skills/deco-v7-to-v8-migration/references/running-the-script.md +29 -0
  121. package/skills/deco-v7-to-v8-migration/references/script-steps.md +13 -0
  122. package/skills/deco-v7-to-v8-migration/references/server-functions.md +15 -0
  123. package/skills/deco-v7-to-v8-migration/references/sibling-port.md +11 -0
  124. package/skills/deco-v7-to-v8-migration/references/site-code.md +15 -0
  125. package/skills/deco-v7-to-v8-migration/references/telemetry.md +10 -0
  126. package/skills/deco-v7-to-v8-migration/references/verify.md +20 -0
  127. package/skills/deco-v7-to-v8-migration/scripts/apps.ts +297 -0
  128. package/skills/deco-v7-to-v8-migration/scripts/asyncRendering.ts +73 -0
  129. package/skills/deco-v7-to-v8-migration/scripts/blockMap.ts +584 -0
  130. package/skills/deco-v7-to-v8-migration/scripts/ciSchemaCheck.ts +145 -0
  131. package/skills/deco-v7-to-v8-migration/scripts/compat.ts +357 -0
  132. package/skills/deco-v7-to-v8-migration/scripts/content.ts +121 -0
  133. package/skills/deco-v7-to-v8-migration/scripts/experiments.ts +81 -0
  134. package/skills/deco-v7-to-v8-migration/scripts/framework.ts +61 -0
  135. package/skills/deco-v7-to-v8-migration/scripts/imageCopy.ts +276 -0
  136. package/skills/deco-v7-to-v8-migration/scripts/imageModule.ts +285 -0
  137. package/skills/deco-v7-to-v8-migration/scripts/imports.ts +942 -0
  138. package/skills/deco-v7-to-v8-migration/scripts/invoke.ts +624 -0
  139. package/skills/deco-v7-to-v8-migration/scripts/legacyNames.ts +45 -0
  140. package/skills/deco-v7-to-v8-migration/scripts/main.ts +59 -0
  141. package/skills/deco-v7-to-v8-migration/scripts/matchers.ts +41 -0
  142. package/skills/deco-v7-to-v8-migration/scripts/migrate.ts +176 -0
  143. package/skills/deco-v7-to-v8-migration/scripts/redirects.ts +455 -0
  144. package/skills/deco-v7-to-v8-migration/scripts/report.ts +50 -0
  145. package/skills/deco-v7-to-v8-migration/scripts/scaffold.ts +1119 -0
  146. package/skills/deco-v7-to-v8-migration/scripts/secrets.ts +35 -0
  147. package/skills/deco-v7-to-v8-migration/scripts/sectionLoaders.ts +216 -0
  148. package/skills/deco-v7-to-v8-migration/scripts/siteSettings.ts +261 -0
  149. package/skills/deco-v7-to-v8-migration/scripts/stubs.ts +388 -0
  150. package/skills/deco-v7-to-v8-migration/scripts/tsconfig.json +7 -0
  151. package/skills/deco-v7-to-v8-migration/scripts/vendor.ts +249 -0
  152. package/skills/deco-v7-to-v8-migration/scripts/vtexInvoke.ts +240 -0
  153. package/skills/deco-v7-to-v8-migration/scripts/walk.ts +30 -0
  154. package/skills/deco-variants/SKILL.md +57 -0
  155. package/skills/deco-variants/references/caching-variants.md +63 -0
  156. package/skills/deco-variants/references/custom-matchers.md +83 -0
  157. package/skills/deco-variants/references/draft-preview.md +59 -0
  158. package/skills/deco-variants/references/experiments-and-campaigns.md +104 -0
  159. package/skills/deco-variants/references/multivariate.md +85 -0
  160. package/skills/deco-variants/references/v7-matchers.md +71 -0
  161. package/src/v8/cli/index.ts +1 -0
  162. package/src/v8/cli/run.ts +35 -1
  163. package/src/v8/cli/skills.ts +91 -0
@@ -0,0 +1,191 @@
1
+ # Uploading assets and rewriting their URLs
2
+
3
+ Two jobs: how uploads work on v8, and how to move a set of assets to a new host
4
+ and point every block at the new URLs.
5
+
6
+ ## The v8 upload endpoint
7
+
8
+ Uploads sit beside the content protocol. The site editor sends each file as
9
+ `PUT /assets/<name>` to the content endpoint, with the file as the body and its
10
+ own `Content-Type`. Whether an endpoint takes uploads is in its `describe`
11
+ answer: `assets` is `{ dir, urlPrefix: "/assets/", maxBytes }`, or `null` when
12
+ the endpoint is read-only or uploads go to hosted storage.
13
+
14
+ What the handler enforces (`packages/blocks/src/protocol/server/assets.ts`,
15
+ naming rules in `protocol/assets.ts`):
16
+
17
+ | Rule | Detail |
18
+ |---|---|
19
+ | Method | `PUT` only; anything else gets 405. |
20
+ | Types | `image/png`, `image/jpeg`, `image/webp`, `image/avif`, `image/gif`, `image/x-icon`, `video/mp4`, `video/webm`, `font/woff2`, `font/woff`, `font/ttf`, `font/otf`, `application/pdf` and a few legacy font and icon types. Others get 415. |
21
+ | SVG | Refused unless the handler is created with `allowSvg`, because SVG can carry scripts that run on the site's origin. |
22
+ | Name | Last path segment only. Accents removed; anything but letters, digits, `.`, `_`, `-` becomes `-`; capped at 200 characters. |
23
+ | Extension | Must match the type (`banner.html` sent as `image/png` gets 415). A name without one gets the type's (`.jpg` for JPEG). The extension is lowercased. |
24
+ | Size | Up to `maxBytes`; 413 above it. Empty bodies are refused. |
25
+ | Collisions | Never overwrites. A taken name gets a random suffix: `banner-3f9a2c.jpg`. |
26
+ | Read-only endpoint | 403. Endpoint without uploads: 404. |
27
+ | Response | `201 { "path": "/assets/<stored name>" }`. That path is what the editor stores in the field. |
28
+
29
+ ### Where the file lands
30
+
31
+ With the filesystem storage (`@decocms/blocks/protocol/storage/fs`, which
32
+ serves a local working tree to the site editor), uploads go to
33
+ `public/assets/` under the app root, or the `assetsDir` option. The default
34
+ `maxBytes` is 25 MB (`assetsMaxBytes` option).
35
+
36
+ So a local upload is **a new file in the repository**, and the field holds the
37
+ relative path `/assets/<name>`. The site serves it from `public/` like any other
38
+ static file. Commit the file and deploy it with the code. If content that
39
+ points at `/assets/x.jpg` is published before the deploy that adds the file,
40
+ the image is a 404 in production until the deploy lands.
41
+
42
+ A relative `/assets/…` path is not a Deco-hosted URL, so the default `decoCdn()`
43
+ does not resize it (see [troubleshooting.md](./troubleshooting.md#not-resized)).
44
+ Upload images at the size they will be shown, or handle these paths with a
45
+ provider of your own.
46
+
47
+ For hosted drafts, `describe` reports `assets: null` and the editor uploads to
48
+ hosted storage. That storage is not part of this repository, so the URL format
49
+ it returns is not documented here. Read a field after uploading to see it.
50
+
51
+ ### What v8 does not have
52
+
53
+ - No `deco` CLI command uploads assets.
54
+ - `createAssetHandler` is internal to `@decocms/blocks` (not exported), so a site
55
+ cannot mount its own upload route from the package.
56
+ - The Fresh-era admin upload API and its cookie-based scripts are not part of
57
+ v8.
58
+
59
+ For bulk uploads to a hosted asset store, use that store's own tools and
60
+ then rewrite URLs as below.
61
+
62
+ ## Moving assets and rewriting URLs in `.deco/blocks`
63
+
64
+ Use this when assets move host: an old bucket shuts down, a migration from
65
+ another CMS, or URLs from a retired CDN. In one measured run, 1,060 assets moved
66
+ this way in about 5 minutes of upload time.
67
+
68
+ ### 0. Start from current content
69
+
70
+ On a site whose content lives in Studio, run `deco pull` first, so
71
+ `.deco/blocks` matches what is published and `deco push` sends only your
72
+ changes. On a site whose content is in git, work on a branch. The commands are
73
+ covered in `deco-site-workflow`.
74
+
75
+ ### 1. Inventory every reference
76
+
77
+ ```bash
78
+ mkdir -p .context
79
+ grep -rhoE 'https?://[a-zA-Z0-9.-]*old-host\.example[^"'"'"'[:space:]\\)]*' .deco/blocks src \
80
+ | sort -u > .context/old-urls.txt
81
+ wc -l .context/old-urls.txt
82
+ ```
83
+
84
+ Search code (`src`) too: hardcoded URLs move with the content.
85
+
86
+ Watch for **wrapped URLs**. Some transform services wrap the original with a
87
+ single slash, such as `https://transform.example/tr:w-1620/https:/old-host.example/a.jpg`.
88
+ The regex above misses the inner one. After the bulk pass, grep for the bare
89
+ host name, without a scheme.
90
+
91
+ ### 2. Upload each asset and record a mapping
92
+
93
+ For each URL: download it, read the real `Content-Type` (old URLs are often
94
+ UUIDs with no extension), give the file the matching extension, upload it,
95
+ and append one line to a mapping file:
96
+
97
+ ```json
98
+ {"old":"https://old-host.example/a/7f3c…","new":"https://<new host>/<path>/banner.jpg","mime":"image/jpeg"}
99
+ ```
100
+
101
+ Rules that save a rerun:
102
+
103
+ - Dedupe the inventory first (`sort -u`). Uploading a URL twice creates two
104
+ assets.
105
+ - Map MIME to extension from the download response, not from the URL. A file
106
+ saved as `.bin` will not render. On the v8 endpoint a wrong extension is
107
+ refused (415).
108
+ - Keep a separate error log, and retry only the failures.
109
+ - Run a few uploads in parallel (around 6), not hundreds. Watch for rate
110
+ limiting and expiring credentials in the error log.
111
+
112
+ ### 3. Check the mapping before touching any file
113
+
114
+ ```bash
115
+ # every URL was mapped
116
+ wc -l .context/old-urls.txt .context/asset-mapping.jsonl
117
+ diff <(sort -u .context/old-urls.txt) \
118
+ <(sed -n 's/.*"old":"\([^"]*\)".*/\1/p' .context/asset-mapping.jsonl | sort -u)
119
+ # every entry has a new URL
120
+ grep -cv '"new":"' .context/asset-mapping.jsonl # must print 0
121
+ ```
122
+
123
+ If any check fails, stop and fix the mapping first.
124
+
125
+ ### 4. Replace with plain strings, not regex
126
+
127
+ URLs are full of characters that mean something in regex and `sed` (`/`, `.`,
128
+ `?`, `&`). Use exact string replacement:
129
+
130
+ ```ts
131
+ // .context/rewrite.ts — run with: bun .context/rewrite.ts (or node)
132
+ import { readFileSync, readdirSync, writeFileSync } from "node:fs";
133
+ import { join } from "node:path";
134
+
135
+ const map = readFileSync(".context/asset-mapping.jsonl", "utf8")
136
+ .split("\n").filter(Boolean).map((l) => JSON.parse(l) as { old: string; new: string });
137
+ const dir = ".deco/blocks";
138
+ let total = 0;
139
+ for (const file of readdirSync(dir).filter((f) => f.endsWith(".json"))) {
140
+ const path = join(dir, file);
141
+ const before = readFileSync(path, "utf8");
142
+ let after = before;
143
+ for (const { old, new: next } of map) {
144
+ const n = after.split(old).length - 1;
145
+ if (n) { total += n; after = after.split(old).join(next); }
146
+ }
147
+ if (after !== before) writeFileSync(path, after);
148
+ }
149
+ console.log(`replaced ${total} references`);
150
+ ```
151
+
152
+ Write the file back byte for byte apart from the URLs: do not re-serialize
153
+ the JSON, so the git diff shows only the URL lines. (`deco diff` compares a
154
+ hash of each block's canonical JSON, so formatting alone does not show there.)
155
+
156
+ ### 5. Verify
157
+
158
+ ```bash
159
+ grep -rn "old-host.example" .deco/blocks src # expect nothing
160
+ ```
161
+
162
+ Anything left is usually a wrapped URL. Replace the whole wrapping URL with the
163
+ new one; the image CDN does the resizing, so the old transform wrapper is not
164
+ needed.
165
+
166
+ Then:
167
+
168
+ - `deco diff` lists changed blocks by name: only the blocks you expect
169
+ should be there. `git diff .deco/blocks` shows the lines.
170
+ - Open a few changed pages locally and check the images load.
171
+ - `deco push --draft=<name>`, then `deco check --draft=<name>` and preview the
172
+ draft. Nothing goes live until `deco publish --draft=<name>`.
173
+
174
+ `deco check` validates block structure, not URLs: image and video fields
175
+ accept any string. Checking that images load is up to you.
176
+
177
+ ### 6. Keep the mapping
178
+
179
+ `.context/` is often git-ignored. If the mapping matters later (rollback,
180
+ audit, a second pass over code), save it somewhere committed.
181
+
182
+ ## Pitfalls
183
+
184
+ | Pitfall | What happens | Fix |
185
+ |---|---|---|
186
+ | URL with no extension | File uploaded with the wrong type, or refused | Use the download's `Content-Type` |
187
+ | Same URL uploaded twice | Two assets, the mapping keeps one | Dedupe first, track in the mapping |
188
+ | Wrapped URLs | Stragglers after the bulk pass | Grep the bare host after step 4 |
189
+ | `sed` replacement | Broken URLs, partial matches | Plain string replacement |
190
+ | Credentials expire mid-run | Uploads start failing quietly | Watch the error log, retry failures |
191
+ | Publishing before the files exist | 404 images in production | Upload and deploy first, publish content last |
@@ -0,0 +1,167 @@
1
+ # Components per binding
2
+
3
+ `@decocms/blocks/image` builds URLs. Each binding turns them into markup its own
4
+ way. In every case the binding gets the site's `ImageUrl` (see
5
+ [providers-and-cdn.md](./providers-and-cdn.md)); it knows no commerce platform
6
+ itself.
7
+
8
+ ## TanStack Start: `@decocms/tanstack/react`
9
+
10
+ Exports: `Image`, `Picture`, `Source`, `ImageUrlProvider`, `useImageUrl`,
11
+ `DECO_IMAGE_URL`, and the prop types `ImageProps`, `PictureProps`,
12
+ `SourceProps`. They keep v7's props and markup, so a v7 call site moves by
13
+ changing the import.
14
+
15
+ ### Wire the site's `ImageUrl` once
16
+
17
+ ```tsx
18
+ // src/router.tsx
19
+ import { ImageUrlProvider } from "@decocms/tanstack/react";
20
+ import { createDecoRouter } from "@decocms/tanstack/router";
21
+ import { imageUrl } from "./imageUrl";
22
+
23
+ createDecoRouter({
24
+ routeTree,
25
+ Wrap: ({ children }) => <ImageUrlProvider value={imageUrl}>{children}</ImageUrlProvider>,
26
+ });
27
+ ```
28
+
29
+ Without a provider, components use `DECO_IMAGE_URL`:
30
+ `createImageUrl({ providers: [decoCdn({ sources: "all" })] })`. That sends
31
+ every source, VTEX and Shopify images included, through
32
+ `assets.decocms.com` with no quality tier. A storefront almost always wants its
33
+ own `imageUrl` with the platform provider first.
34
+
35
+ `ImageUrlProvider` is a React context. A nested provider overrides it for one
36
+ subtree, which is how you give one area a different tier (see
37
+ [quality-and-lcp.md](./quality-and-lcp.md)). `useImageUrl()` returns the nearest
38
+ one, for code that needs a URL outside the components (a CSS background, an
39
+ Open Graph tag).
40
+
41
+ ### `Image`
42
+
43
+ ```tsx
44
+ <Image src={src} width={640} height={480} alt={alt} />
45
+ ```
46
+
47
+ | Prop | Default | Effect |
48
+ |---|---|---|
49
+ | `src`, `width` | required | `width` is the 1x width and the base of the srcset. |
50
+ | `height` | none | Sent to the provider and set on the `<img>`. |
51
+ | `fit` | `"cover"` | Passed to the provider. |
52
+ | `preload` | `false` | Renders a `<link rel="preload" as="image">` next to the `<img>`, and sets `loading="eager"` and `fetchPriority="high"`. |
53
+ | `media` | none | `media` on that preload link. |
54
+ | `sizes` | `"(max-width: 768px) 100vw, 50vw"` when there is a srcset | Override it to match the real layout. |
55
+ | `srcSet` | built | Overrides the generated srcset. |
56
+ | `loading` | `"lazy"`, or `"eager"` with `preload` | |
57
+ | `decoding` | `"async"` | |
58
+
59
+ Every other `<img>` attribute passes through. There is **no `quality` prop**:
60
+ quality comes from the `ImageUrl`.
61
+
62
+ The generated srcset has two width candidates, `width` and `2 × width`
63
+ (`height` scaled the same way), written as `<url> 640w, <url> 1280w`.
64
+
65
+ ### `Picture` and `Source`
66
+
67
+ Art direction: one `Source` per media query and an `Image` fallback.
68
+
69
+ ```tsx
70
+ <Picture preload={isLcp}>
71
+ <Source media="(max-width: 767px)" src={mobile} width={375} height={184} />
72
+ <Source media="(min-width: 768px)" src={desktop} width={1280} height={480} />
73
+ <Image src={desktop} width={1280} height={480} alt={alt} />
74
+ </Picture>
75
+ ```
76
+
77
+ With `<Picture preload>`, each `Source` renders its own preload link with its
78
+ `media`, so the browser preloads only the one that applies. `Source` takes
79
+ `src`, `width`, `height`, `fit` (default `"cover"`), `fetchPriority` and any
80
+ `<source>` attribute. Do not also set `preload` on the fallback `Image` inside a
81
+ preloading `Picture`: that adds a second preload with no `media`.
82
+
83
+ ## Next.js: `@decocms/nextjs/image-loader`
84
+
85
+ next/image renders the markup; Deco only provides the loader.
86
+
87
+ ```ts
88
+ // src/image-loader.ts
89
+ import { createDecoImageLoader } from "@decocms/nextjs/image-loader";
90
+ import { imageUrl } from "./imageUrl";
91
+ export default createDecoImageLoader(imageUrl);
92
+ ```
93
+
94
+ ```js
95
+ // next.config: images: { loader: "custom", loaderFile: "./src/image-loader.ts" }
96
+ ```
97
+
98
+ The loader receives `{ src, width, quality }` from next/image:
99
+
100
+ - If `imageUrl.isOptimizable(src)`, it returns `imageUrl(src, { width, quality })`.
101
+ next/image passes no height or fit, so providers get width only.
102
+ - Otherwise it calls `fallback(props)`. With no `fallback`, or one that returns
103
+ `null`, `src` comes back unchanged.
104
+
105
+ For local `/public` files or other hosts no provider handles, use Next's own
106
+ optimizer as the fallback:
107
+
108
+ ```ts
109
+ import { createDecoImageLoader, nextImageOptimizer } from "@decocms/nextjs/image-loader";
110
+ export default createDecoImageLoader(imageUrl, { fallback: nextImageOptimizer });
111
+ ```
112
+
113
+ `nextImageOptimizer` builds `/_next/image?url=&w=&q=`, turning tiers into
114
+ 60/70/80/100. The host still has to be allowed in `images.remotePatterns`.
115
+
116
+ Quality: next/image's `quality` prop is a number. `decoCdn` ignores numbers, so
117
+ on Deco-CDN images the tier set in `decoCdn({ quality })` decides.
118
+ `vtexCatalogWebp` and `vtexFileManager` do read numbers; `vtexCatalog`,
119
+ `vtexCatalogFrame` and `shopifyCdn` ignore quality.
120
+
121
+ `sizes`, priority and preload are next/image's own props; follow the Next.js
122
+ docs for your version. Wiring `next.config` is covered in `deco-nextjs-site`.
123
+
124
+ ## Any other renderer: `srcSet` and `preloadLink`
125
+
126
+ Both take the `ImageUrl` as the first argument.
127
+
128
+ ```ts
129
+ import { srcSet, preloadLink, parseSrcSet } from "@decocms/blocks/image";
130
+
131
+ srcSet(imageUrl, src, { width: 640, height: 480 }); // factors [1, 2]
132
+ srcSet(imageUrl, src, { widths: [320, 640, 1280], ratio: 0.75 }); // explicit widths, height = round(w × ratio)
133
+ preloadLink(imageUrl, src, { width: 1280, sizes: "100vw", media: "(min-width: 768px)" });
134
+ ```
135
+
136
+ - `srcSet` options: `width`, `widths` (wins over `width` and `factors`),
137
+ `factors` (default `[1, 2]`, truncated), `height`, `ratio`, `fit`, `quality`.
138
+ Returns `undefined` for an empty `src` or no candidates. Without `width` or
139
+ `widths` it writes `NaN` candidates, as v7 did: always pass one.
140
+ - `preloadLink` returns `{ rel: "preload", as: "image", href, imageSrcSet?,
141
+ imageSizes?, media?, fetchPriority }`, `fetchPriority` defaulting to
142
+ `"high"`. Spread it into a `<link>` or a route's head links.
143
+ - `parseSrcSet(s)` splits a srcset attribute into `{ url, w?, x? }`, keeping
144
+ URLs with commas whole. Useful in tests.
145
+
146
+ ## Image fields in section props
147
+
148
+ The schema generator gives an image picker to a string prop typed with the
149
+ alias `ImageWidget`, and a video picker to `VideoWidget`. Both are exported
150
+ from `@decocms/compat-v7/types/widgets` (plain `string` aliases).
151
+ `@format image-uri` or `@format video-uri` on a string does the same.
152
+
153
+ ```ts
154
+ import type { ImageWidget } from "@decocms/compat-v7/types/widgets";
155
+
156
+ interface Props {
157
+ /** @description Desktop image, at least 2560×960 (2× the 1280×480 slot) */
158
+ image: ImageWidget;
159
+ alt: string;
160
+ }
161
+ ```
162
+
163
+ `deco check` does not validate these values: `image-uri` and `video-uri` accept
164
+ any string, so a broken URL passes the check. Put the 2x pixel size in the
165
+ field's `@description` (the generated schema carries it to the editor's form), so
166
+ editors upload large enough files. Field annotations in general are in
167
+ `deco-cms-schema`.
@@ -0,0 +1,145 @@
1
+ # Providers and the Deco image CDN
2
+
3
+ `@decocms/blocks/image` is pure functions: no React, no framework, no module
4
+ state. A site composes an `ImageUrl` from `ImageProvider`s and passes it to its
5
+ binding (see [components-per-binding.md](./components-per-binding.md)).
6
+
7
+ ## The pieces
8
+
9
+ ```ts
10
+ interface ResizeOptions { width: number; height?: number; fit?: Fit; quality?: Quality }
11
+ type Fit = "contain" | "cover" | "fill";
12
+ type Quality = "low" | "medium" | "high" | "original" | number;
13
+
14
+ interface ImageProvider {
15
+ name: string;
16
+ match(src: string): boolean; // does this provider handle src?
17
+ format(src: string, o: ResizeOptions): string | null; // null: leave src to the next provider
18
+ hosts?: string[]; // hosts its URLs point at
19
+ }
20
+
21
+ const imageUrl = createImageUrl({ providers: [/* in order */] });
22
+ imageUrl(src, { width: 640 }); // resized URL
23
+ imageUrl.isOptimizable(src); // some provider matches (false for "", data:, unknown)
24
+ imageUrl.hosts(); // every provider's hosts, deduplicated
25
+ ```
26
+
27
+ Order matters. `createImageUrl` walks the list, skips providers whose `match`
28
+ is false, and returns the first non-null `format`. Put the narrow providers
29
+ (platform catalogs) first and the broad one (`decoCdn({ sources: "all" })`) last.
30
+
31
+ ## `decoCdn(options)`
32
+
33
+ Builds `https://<domain>/image?fit=&width=[&height=][&quality=]&src=<path>`.
34
+
35
+ | Option | Default | What it does |
36
+ |---|---|---|
37
+ | `domain` | `"assets.decocms.com"` | CDN host. `decoims.com` and `deco-assets.edgedeco.com` serve the same endpoint. A scheme or trailing slash is stripped. |
38
+ | `quality` | none | Tier used when a call names none. Without it, no `quality` param is sent and the CDN uses its own default (60% per the code's comment). |
39
+ | `fit` | `"cover"` | Fit when a call names none. |
40
+ | `sources` | `"deco"` | Which sources it resizes. `"deco"`: the Deco asset hosts, `domain` and `legacyHosts`. `"all"`: any non-empty, non-`data:` source. Or a predicate `(src) => boolean`. |
41
+ | `legacyHosts` | `["decoims.com"]` when `domain` is `assets.decocms.com`, else `[]` | Older CDN hosts whose URLs are re-served from `domain`. |
42
+ | `stripAssetHosts` | `"leading"` | How `https://assets.decocache.com/` and the `deco-sites-assets` S3 bucket prefix are removed from the source. `"leading"`: only when the source starts with one. `"anywhere"`: the first occurrence of each, wherever it is. |
43
+ | `layout` | `"src-last"` | Query order. `"quality-last"` matches what next/image loaders built on v7's helper wrote. Keep the one the site used before, so the CDN cache stays warm. |
44
+
45
+ Behaviour worth knowing:
46
+
47
+ - **The source's query string is dropped.** `decoCdn` keeps only the part of
48
+ `src` before `?`.
49
+ - **Already-resized URLs are unwrapped.** A source that is itself a Deco CDN
50
+ `/image?…&src=…` URL (on any of its hosts) is re-resized from its inner `src`.
51
+ Resizing twice gives the same URL.
52
+ - **Self-fetch loop on Cloudflare hosts.** On `assets.decocms.com` and
53
+ `decoims.com`, a `decoims.com` source is stripped to its path. The code notes
54
+ that a `decoims.com` `src=` there makes the CDN fetch itself (508). On the
55
+ Azion hosts (`deco-assets.edgedeco.com`, `deco-assets.decoazn.com`) the full
56
+ `decoims.com` URL is kept, since they fetch it fine.
57
+ - **Numbers are ignored.** `quality: 90` on a call falls back to the
58
+ `quality` option. Only the four tier names reach the CDN.
59
+ - `hosts` is `[domain]`.
60
+
61
+ ## Platform providers
62
+
63
+ These live in the platform's client package, not in `@decocms/blocks`. List them
64
+ before `decoCdn`.
65
+
66
+ ### VTEX: `@decocms/apps-vtex/image`
67
+
68
+ Each reproduces one URL format sites already use, byte for byte. Pick the one
69
+ the site's old helper matched; changing format changes every image URL and
70
+ empties the CDN cache.
71
+
72
+ | Provider | Matches | Output |
73
+ |---|---|---|
74
+ | `vtexCatalog()` | `*.vteximg.com.br`, `*.vtexassets.com`, `*.myvtex.com` URLs with `/arquivos/ids/{id}` | `/arquivos/ids/{id}-{width}-{height ?? width}/…` (v7's `Image`). Ignores quality. |
75
+ | `vtexCatalogFrame({ frame? })` | Any host with `/arquivos/ids/{id}[-w-h]/` | `{id}-{w}-{h}`. With `frame: { width, height }`, height is always `round(width × frame.height / frame.width)`; VTEX fills the rest with white. |
76
+ | `vtexCatalogWebp({ quality? })` | Any URL with `/ids/{id}` and a file extension | `/ids/{id}-{width}-auto/{file}.webp?…&quality=` (VTEX keeps the ratio). Without an extension it returns null. |
77
+ | `vtexFileManager({ via, quality? })` | URLs containing `vtexassets` and `/assets` (file-manager images) | `via: "query"`: `?width=&aspect=true&quality=`. `via: "thumbor"`: PNG/JPEG/WebP through `/unsafe/{w}x0/filters:…:format(webp)/…`; SVG and GIF unchanged. |
78
+
79
+ VTEX quality is on a 1 to 10 scale. Tiers map to 60/70/80/100 and then to
80
+ 6/7/8/10; numbers above 10 are read as 1 to 100, divided by 10 and rounded up. Default 8.
81
+
82
+ ```ts
83
+ import { createImageUrl, decoCdn } from "@decocms/blocks/image";
84
+ import { vtexCatalog, vtexFileManager } from "@decocms/apps-vtex/image";
85
+
86
+ export const imageUrl = createImageUrl({
87
+ providers: [
88
+ vtexCatalog(),
89
+ vtexFileManager({ via: "query" }),
90
+ decoCdn({ sources: "all", quality: "high" }),
91
+ ],
92
+ });
93
+ ```
94
+
95
+ ### Shopify: `@decocms/apps-shopify/image`
96
+
97
+ `shopifyCdn()` matches `https://cdn.shopify.com…` and sets `width`, `height`
98
+ (when given) and `crop=center` on the query. It ignores `quality` and `fit`.
99
+
100
+ ### Other platforms
101
+
102
+ No other `@decocms/apps-*` package ships an image provider. If a platform's CDN
103
+ resizes by URL, write a provider in the site:
104
+
105
+ ```ts
106
+ import type { ImageProvider } from "@decocms/blocks/image";
107
+
108
+ export const platformCdn: ImageProvider = {
109
+ name: "platform",
110
+ hosts: ["images.platform.example"],
111
+ match: (src) => src.startsWith("https://images.platform.example/"),
112
+ format(src, { width, height }) {
113
+ const url = new URL(src);
114
+ url.searchParams.set("w", String(width));
115
+ if (height) url.searchParams.set("h", String(height));
116
+ return url.href;
117
+ },
118
+ };
119
+ ```
120
+
121
+ Return `null` from `format` for a source you matched but cannot resize, so the
122
+ next provider gets it. Without a provider, `decoCdn({ sources: "all" })` sends
123
+ those images through the Deco CDN instead, which also works.
124
+
125
+ ## `hosts()` for CSP and preconnect
126
+
127
+ `imageUrl.hosts()` lists every provider's hosts once, wildcards included (the
128
+ VTEX providers report `*.vtexassets.com` and similar). No binding reads it for
129
+ you. If the site sets a Content-Security-Policy, add these hosts to `img-src`;
130
+ the CSP itself is set up as described in `deco-tanstack-site` or
131
+ `deco-nextjs-site`. A source that passes through unchanged loads from its own
132
+ host, which `hosts()` does not list.
133
+
134
+ ## Which `decoCdn` setup to start from
135
+
136
+ | Site | Providers |
137
+ |---|---|
138
+ | Content site, images uploaded to Deco | `[decoCdn({ quality: "high" })]` |
139
+ | Images from many hosts, all through the Deco CDN | `[decoCdn({ sources: "all", quality: "high" })]` (this is what TanStack's default does, without the tier) |
140
+ | VTEX storefront | `[vtexCatalog(), decoCdn({ sources: "all", quality: "high" })]` |
141
+ | Shopify storefront | `[shopifyCdn(), decoCdn({ sources: "all", quality: "high" })]` |
142
+ | Migrated v7 site | Match the old domain, quality and layout exactly, so URLs do not change. `deco-v7-to-v8-migration` reads these from the site's old helper. |
143
+
144
+ `"high"` above is a starting point, not a package default. See
145
+ [quality-and-lcp.md](./quality-and-lcp.md).
@@ -0,0 +1,93 @@
1
+ # Quality tiers, sizes and the LCP image
2
+
3
+ ## Tiers
4
+
5
+ The Deco CDN takes four named tiers. Other code in the packages maps them to
6
+ percentages:
7
+
8
+ | Tier | Percent (VTEX providers, `nextImageOptimizer`) |
9
+ |---|---|
10
+ | `low` | 60 |
11
+ | `medium` | 70 |
12
+ | `high` | 80 |
13
+ | `original` | 100 |
14
+
15
+ With no tier, `decoCdn` sends no `quality` parameter and the CDN applies its own
16
+ default (60% per the comment in `image.ts`). That is the same percentage the
17
+ table above gives `low`, so a site that never sets a tier should expect
18
+ low-tier quality on every Deco-CDN image.
19
+
20
+ ## Where quality is set
21
+
22
+ | Level | How | Notes |
23
+ |---|---|---|
24
+ | Whole site | `decoCdn({ quality: "high" })` in the site's `imageUrl` | The usual place. This is v7's `registerImageQuality`. |
25
+ | One subtree (TanStack) | A nested `<ImageUrlProvider value={otherImageUrl}>` built with another tier | `Image`, `Picture` and `Source` have no `quality` prop. |
26
+ | One URL | `imageUrl(src, { width, quality: "original" })`, `srcSet(imageUrl, src, { …, quality })`, `preloadLink(…, { quality })` | A call's tier wins over the `decoCdn` option. Numbers are ignored by `decoCdn`. |
27
+ | next/image | `decoCdn({ quality })` | next/image's numeric `quality` is ignored by `decoCdn`; `vtexCatalogWebp` and `vtexFileManager` read it. |
28
+
29
+ The "Default Image Quality" field of the Fresh-era website app has no v8
30
+ equivalent. Quality is code. To let editors change it, read a value from a
31
+ settings block and build the `ImageUrl` from it; that is site code, not a
32
+ package feature.
33
+
34
+ Choosing a tier:
35
+
36
+ - `high` for product photos, hero banners, anything people zoom into.
37
+ - `medium` is a fair balance for thumbnails and grids.
38
+ - `low` shows visible artifacts on product photography. Avoid it as a
39
+ site-wide value.
40
+ - `original` adds bytes, not detail. A source that is too small stays blurry
41
+ at any tier (see [troubleshooting.md](./troubleshooting.md)).
42
+
43
+ ## `sizes` and the srcset
44
+
45
+ `Image` and `Source` emit two width candidates: `width` and `2 × width`. The
46
+ browser picks one using `sizes`. When `sizes` is not set, `Image` uses
47
+ `"(max-width: 768px) 100vw, 50vw"`.
48
+
49
+ That default fits a two-column layout. For a full-width hero on desktop it
50
+ tells the browser the image is half the viewport, so it may pick the smaller
51
+ candidate and the hero looks soft on large screens. Set `sizes` to the slot's
52
+ real width, e.g. `sizes="100vw"` for a full-bleed banner, or
53
+ `"(max-width: 768px) 100vw, 1280px"` for a fixed container.
54
+
55
+ If one slot spans many widths (fluid grids), pass explicit candidates instead
56
+ of factors: `srcSet={srcSet(useImageUrl(), src, { widths: [360, 720, 1080, 1440], ratio: 0.5 })}`.
57
+
58
+ ## Preloading the LCP image
59
+
60
+ Preload exactly one image per page: the one that is the Largest Contentful
61
+ Paint on first view. Usually the first hero banner or the main product photo.
62
+
63
+ - TanStack, one image: `<Image preload … />`. It renders a preload link,
64
+ `loading="eager"` and `fetchPriority="high"`.
65
+ - TanStack, art-directed: `<Picture preload>` with a `Source` per media query.
66
+ Each `Source` preloads with its own `media`, so a phone does not download the
67
+ desktop banner.
68
+ - Head links: `preloadLink(imageUrl, src, { width, sizes, media })` returns the
69
+ attributes for a `<link>` in the route's head.
70
+ - Next.js: use next/image's own preload or priority option.
71
+
72
+ Rules:
73
+
74
+ - **Preload only what renders above the fold on first load.** A preload for a
75
+ carousel's second slide or a below-the-fold section wastes bandwidth the LCP
76
+ image needs.
77
+ - **Make the preload match the `<img>`.** Same `src`, same `width`/`height`,
78
+ same `sizes`. Otherwise the browser downloads two files. `Image` builds both
79
+ from the same props, so this holds as long as you do not also write a manual
80
+ preload. A `Source` preload link carries no `imageSizes`, so give the
81
+ `Source` no `sizes` either, or write that preload yourself with
82
+ `preloadLink`.
83
+ - **Sections decide preload from props.** A banner section usually takes a
84
+ `preload` or "is LCP" boolean, set on the first instance in the page. Do not
85
+ hardcode `preload` in a component that appears many times.
86
+ - **Never lazy-load the LCP image.** `loading="lazy"` on it delays LCP. `Image`
87
+ defaults to lazy unless `preload` is set.
88
+ - **Always set `width` and `height`.** They give the box its aspect ratio
89
+ before the file arrives, which avoids layout shift.
90
+
91
+ For measuring LCP and CLS on a page, and fixes beyond images, load
92
+ `deco-storefront-performance`. Generic HTML guidance (formats, `fetchpriority`,
93
+ media-specific preloads) is in `image-optimizer` (decocms/skills).