@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,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).
|