@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,146 @@
|
|
|
1
|
+
# Edit content from the terminal
|
|
2
|
+
|
|
3
|
+
The remote commands move content between `.deco/blocks` and Studio's hosted CMS for the site named by
|
|
4
|
+
`DECO_SITE`. Reads of published content and drafts go to the public CDN. Writes go through the Studio
|
|
5
|
+
API with your token. Nothing retries on its own, and nothing goes live except `deco publish`.
|
|
6
|
+
|
|
7
|
+
Token and site setup: [schema.md](./schema.md), Steps 2 and 3.
|
|
8
|
+
|
|
9
|
+
## The edit loop
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
deco pull # or: deco pull --draft=summer-sale
|
|
13
|
+
# edit .deco/blocks/*.json (or add files)
|
|
14
|
+
deco diff # what you changed since the pull
|
|
15
|
+
deco push --draft=summer-sale # one save; prints "preview: <link>"
|
|
16
|
+
deco check --draft=summer-sale # the whole draft against the code
|
|
17
|
+
# open the preview link and look at the pages
|
|
18
|
+
deco publish --draft=summer-sale --message="Summer sale banners"
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Adding a page, as an example: pull, copy an existing page's file (it already references the shared
|
|
22
|
+
`Header` and `Footer` blocks), give the copy a new file name, `name` and `path`, change its
|
|
23
|
+
`sections`, then diff, push, check and preview. Use a block type that is in the deployed code, or
|
|
24
|
+
`deco check` fails and Studio has no form for it. What a page's props mean is `deco-site-authoring`.
|
|
25
|
+
|
|
26
|
+
## pull
|
|
27
|
+
|
|
28
|
+
`deco pull [--draft=<name>] [--force]`
|
|
29
|
+
|
|
30
|
+
- Without `--draft`: writes production (the live release) into `.deco/blocks`. With it: production
|
|
31
|
+
with that draft's changes on top.
|
|
32
|
+
- Makes the folder hold exactly that content: it writes each block and **removes every other block
|
|
33
|
+
file**.
|
|
34
|
+
- Writes `.deco/pull.json`: per block, its hash and its version in the draft.
|
|
35
|
+
- Refuses when the folder has changes not pushed:
|
|
36
|
+
`.deco/blocks has 3 changes not pushed (A, B, C); push them, or pull with --force to overwrite them`
|
|
37
|
+
(exit 1). `--force` overwrites them.
|
|
38
|
+
- Prints `pulled 42 blocks from production (revision <id>)` or `… from draft <name> (over revision <id>)`.
|
|
39
|
+
|
|
40
|
+
## diff
|
|
41
|
+
|
|
42
|
+
`deco diff [--draft=<name>]`
|
|
43
|
+
|
|
44
|
+
- Without `--draft`: what `.deco/blocks` changes against `.deco/pull.json`, shown against what was
|
|
45
|
+
pulled (or, after a draft pull, against that draft **as it is now**, which the label says).
|
|
46
|
+
`nothing pulled yet: run deco pull` (exit 1) when there is no `pull.json`.
|
|
47
|
+
- With `--draft`: the folder against that draft as it is now, ignoring `pull.json`.
|
|
48
|
+
- One line per block: `M` changed, `A` new, `D` deleted, each with a field diff. Then
|
|
49
|
+
`3 changes against …` or `no changes against …`.
|
|
50
|
+
|
|
51
|
+
## push
|
|
52
|
+
|
|
53
|
+
`deco push --draft=<name> [--ours | --theirs] [--prune]`
|
|
54
|
+
|
|
55
|
+
- Creates the draft if it doesn't exist (`created draft <name>`).
|
|
56
|
+
- Sends only blocks changed since the pull. A block that already equals what the draft shows is
|
|
57
|
+
skipped. With no `pull.json`, every file is new.
|
|
58
|
+
- **Deletes are sent only with `--prune`.** Without it the push names what it skipped:
|
|
59
|
+
`not sent: 1 deleted block (Old); push with --prune to send deletes`.
|
|
60
|
+
- Each block carries a precondition: its version in the draft when you pulled. If someone changed
|
|
61
|
+
it since, nothing of the save is written and the push **exits 2**:
|
|
62
|
+
|
|
63
|
+
```text
|
|
64
|
+
conflict: Home: changed by <user> at <time>; theirs (-) against yours (+)
|
|
65
|
+
1 block changed in draft summer-sale while you pushed; nothing of this save was written. Pull again, or push with --ours (keep yours) or --theirs (take theirs)
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
- `--ours`: send yours again over theirs.
|
|
69
|
+
- `--theirs`: write their version into `.deco/blocks` for the conflicting blocks and send the rest.
|
|
70
|
+
- `--ours` and `--theirs` together is a usage error (64).
|
|
71
|
+
- Pushing to a draft other than the one you pulled drops the preconditions: a name that draft already
|
|
72
|
+
changed comes back as a conflict.
|
|
73
|
+
- One push is one save. It must fit **500 blocks and 8 MiB**, and each block **1 MiB**. Otherwise
|
|
74
|
+
nothing is sent: `the 812 changed blocks don't fit one save (…); push fewer at a time`, or
|
|
75
|
+
`block "<name>" is larger than a save can carry (1048576 bytes a block)`. To push a large folder,
|
|
76
|
+
move part of the files out, push, move them back, push again: blocks already pushed are recorded in
|
|
77
|
+
`pull.json` and skipped.
|
|
78
|
+
- Busy Studio (exit 5): `Studio is busy (…); 120 blocks saved, the rest not, run deco push again`.
|
|
79
|
+
Run it again; what landed is recorded.
|
|
80
|
+
- A file that isn't a valid block stops the push before anything is sent (exit 1), for example
|
|
81
|
+
`.deco/blocks/Home.json: invalid JSON: …`.
|
|
82
|
+
- Prints `pushed 3 blocks to draft summer-sale` and `preview: <link>`.
|
|
83
|
+
|
|
84
|
+
`deco push` does not run `deco check`. Run `deco check --draft=<name>` after it.
|
|
85
|
+
|
|
86
|
+
## drafts
|
|
87
|
+
|
|
88
|
+
| Command | Does |
|
|
89
|
+
|---|---|
|
|
90
|
+
| `deco drafts list` | Each draft: name, who created it, via what, when (`no drafts` when none) |
|
|
91
|
+
| `deco drafts new <name>` | Creates it (`draft <name> already exists` if it does) and prints its preview link, when Studio has one |
|
|
92
|
+
| `deco drafts discard <name>` | Deletes the draft and its changes |
|
|
93
|
+
| `deco drafts url <name>` | Prints the preview URL; or the pointer, to open as `?__draft=<pointer>` on the site; or `draft <name> has no object yet: push to it first` |
|
|
94
|
+
|
|
95
|
+
Draft names: letters, digits and `/ . _ -` after the first character, at most 255. Anything else is
|
|
96
|
+
exit 64: `"<value>" isn't a draft name: …`.
|
|
97
|
+
|
|
98
|
+
## publish
|
|
99
|
+
|
|
100
|
+
`deco publish --draft=<name> [--message=<text>]`
|
|
101
|
+
|
|
102
|
+
- Prints what the draft changes against production (same `M`/`A`/`D` view), then publishes.
|
|
103
|
+
- `published revision <id>; it is live`. The site follows within about a minute
|
|
104
|
+
([delivery.md](./delivery.md)). No deploy.
|
|
105
|
+
- `nothing to publish: production already has every block of draft <name>` when there is nothing.
|
|
106
|
+
- A draft saved during the publish is not emptied, and the CLI warns:
|
|
107
|
+
`draft <name> was saved during the publish, so it wasn't emptied: it still holds its blocks`.
|
|
108
|
+
- Exit 5 when production moved during the publish (Studio's `production_moved`): run it again.
|
|
109
|
+
- It does not run `deco check`. Run `deco check --draft=<name>` first.
|
|
110
|
+
|
|
111
|
+
## releases and rollback
|
|
112
|
+
|
|
113
|
+
`deco releases [--cursor=<cursor>]` lists published revisions, newest first, 50 a page:
|
|
114
|
+
|
|
115
|
+
```text
|
|
116
|
+
<id> current 2026-11-06T21:10:38Z <author> via <via> draft summer-sale "Summer sale banners"
|
|
117
|
+
<id> 2026-11-05T… <author> via <via> rollback to <id>
|
|
118
|
+
<id> unreadable (its meta.json couldn't be read)
|
|
119
|
+
more: deco releases --cursor=<cursor>
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
`current` marks the revision `latest.json` names.
|
|
123
|
+
|
|
124
|
+
There is no rollback command in the CLI; rollbacks are made in Studio. A rollback publishes a new
|
|
125
|
+
revision that re-applies an old one, and `deco releases` shows it as `rollback to <id>`. Before you roll back,
|
|
126
|
+
check that the old content still fits the code that is deployed now:
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
deco check --revision=<id>
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
A rollback to content that uses a block type the code no longer has breaks those pages. Fix forward
|
|
133
|
+
with a draft instead in that case.
|
|
134
|
+
|
|
135
|
+
## Errors worth recognizing
|
|
136
|
+
|
|
137
|
+
| Message | Exit | Meaning |
|
|
138
|
+
|---|---|---|
|
|
139
|
+
| `no Studio site: set DECO_SITE …` | 64 | No `DECO_SITE` anywhere ([schema.md](./schema.md)) |
|
|
140
|
+
| `no .deco/ found from <dir>; run inside your app or pass --root` | 64 | Wrong folder |
|
|
141
|
+
| `deco push needs --draft=<name>` | 64 | `push` and `publish` always need a draft |
|
|
142
|
+
| `not logged in to …; run: npx decocms auth login --target=…` | 3 | No token |
|
|
143
|
+
| `Studio answered <status>: <message>` | 1, 3, 4 or 5 | Studio's own error, mapped to an exit code ([cli-reference.md](./cli-reference.md)) |
|
|
144
|
+
| `the CDN has no revision <id>` | 1 | `pull.json` names a revision the CDN doesn't have: pull again |
|
|
145
|
+
| `.deco/pull.json isn't one deco pull wrote; run deco pull` | 1 | Corrupt or hand-edited `pull.json` |
|
|
146
|
+
| `Studio refused the save: …` | 1 or 3 | Studio rejected the content or the token |
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# How published content reaches the site
|
|
2
|
+
|
|
3
|
+
With `createCMS({ blocks, site })`, content is never in the bundle. The site reads it at runtime from
|
|
4
|
+
`https://delivery.decocms.com/sites/<site>/`, over plain HTTP with no credential. The CDN layout is in
|
|
5
|
+
[content-layout.md](./content-layout.md#on-the-cdn).
|
|
6
|
+
|
|
7
|
+
## The release index
|
|
8
|
+
|
|
9
|
+
- The first request loads `latest.json`, the current release's index. Requests that arrive meanwhile
|
|
10
|
+
share that one load. Each fetch has 10 s.
|
|
11
|
+
- If that first load fails, a 404 included (the site was never published), clients answer
|
|
12
|
+
`LOADER_FAILED` with a `ContentUnavailableError` cause. There is no bundled fallback and never an
|
|
13
|
+
empty site. A failed load isn't kept: the next request tries again.
|
|
14
|
+
- After that, the CMS checks for a new release in the background every `interval` (default and
|
|
15
|
+
minimum 60 000 ms, plus or minus up to 10 s). A request starts the check and never waits for it. The
|
|
16
|
+
check sends `If-None-Match`, so an unchanged index is a 304.
|
|
17
|
+
- A read is adopted only if its `sequence` is higher than the one held, so a stale CDN answer never
|
|
18
|
+
moves the site backwards. A failed check keeps the last good index.
|
|
19
|
+
|
|
20
|
+
So a publish shows on a given isolate within about 70 s, without a deploy.
|
|
21
|
+
|
|
22
|
+
## Blocks
|
|
23
|
+
|
|
24
|
+
- A request walks the routes and references in the index, then fetches the bodies it needs by hash
|
|
25
|
+
(`blocks/<hash>.json`) in one parallel wave. A body never changes, so it is cached per isolate in an
|
|
26
|
+
LRU of 32 MiB of JSON. Concurrent requests share one fetch per hash.
|
|
27
|
+
- Each request pins the index it started with.
|
|
28
|
+
- Right after a publish, a page whose new blocks aren't cached yet is served from the previous index
|
|
29
|
+
while they load in the background. The next request gets the new content.
|
|
30
|
+
- An index or a body over 16 MiB is refused.
|
|
31
|
+
|
|
32
|
+
## Drafts and old releases
|
|
33
|
+
|
|
34
|
+
- A draft request (`?__draft=…` or the draft cookie) always revalidates at the CDN and never shares the
|
|
35
|
+
isolate's cached copy. It checks for the latest release once, so a preview shows a release published
|
|
36
|
+
a moment ago.
|
|
37
|
+
- A link with a release id in place of a draft (Studio's "Preview this version") reads
|
|
38
|
+
`revisions/<id>/index.json`. The last three such indexes are kept in memory.
|
|
39
|
+
- Previews only open on allowed hosts: see [serve-and-studio.md](./serve-and-studio.md#step-5-previews-in-studio-and-on-your-machine).
|
|
40
|
+
- The TanStack worker never hands a preview to the site's page cache and answers it with
|
|
41
|
+
`Cache-Control: max-age=0, no-cache, must-revalidate`, `Vary: Cookie` and `noindex`.
|
|
42
|
+
|
|
43
|
+
## When a publish doesn't show
|
|
44
|
+
|
|
45
|
+
| Check | Meaning |
|
|
46
|
+
|---|---|
|
|
47
|
+
| `deco releases`: is your revision `current`? | If not, the publish didn't happen or someone published after you |
|
|
48
|
+
| `curl -s https://delivery.decocms.com/sites/<site>/latest.json` and compare `revision` | The CDN has it; the site may not have polled yet. Wait about a minute |
|
|
49
|
+
| The page comes from your page cache | Key the cache on the content revision (`cacheVersion(cms, buildHash, url)` from `@decocms/tanstack/worker`). See `deco-storefront-caching` |
|
|
50
|
+
| The content is read outside the CMS client | Code that imports `.deco/blocks/*.json` directly, or a build script that reads `.deco/blocks`, stays on the last deploy. Read it through the client |
|
|
51
|
+
| The site runs without `site` | A bundled site (`content`) changes only with a deploy |
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# Deploy: order, CI and secrets
|
|
2
|
+
|
|
3
|
+
Code ships with a deploy. Content ships with a publish. The schema is how Studio learns about the
|
|
4
|
+
code. Each of the three can break the others if they go out in the wrong order.
|
|
5
|
+
|
|
6
|
+
## Variables and secrets
|
|
7
|
+
|
|
8
|
+
| Name | Read by | Secret? | Where it lives |
|
|
9
|
+
|---|---|---|---|
|
|
10
|
+
| `DECO_SITE` | the CLI; your code, to pass `createCMS({ site })` | no | `wrangler.jsonc` `vars` (Workers), `.env`, or CI env. The CLI also reads `.dev.vars` |
|
|
11
|
+
| `DECO_TOKEN` | the CLI only | **yes** | CI secrets, or your shell. Never in the site's runtime env or in git |
|
|
12
|
+
| `DECO_STUDIO_URL` | the CLI only | no | Unset, except for a local or staging Studio |
|
|
13
|
+
| `DECO_STUDIO_ORIGIN` | the bindings, at runtime | no | Unset, except to trust a local Studio's origin |
|
|
14
|
+
| the site token passed as `createCMS({ token })` | your code | **yes** | A runtime secret (for example a Worker secret). Only for hosted telemetry |
|
|
15
|
+
|
|
16
|
+
Commerce keys and other upstream credentials are runtime secrets of the deploy platform, read by code
|
|
17
|
+
and passed as params. Content never holds secrets: `deco check` rejects the old `secret` blocks. On
|
|
18
|
+
deco's own hosting, how env vars and secrets are set is `deco-control-plane-ops` (decocms/skills).
|
|
19
|
+
|
|
20
|
+
`DECO_TOKEN` is a Studio API key. Without it, the CLI runs `npx decocms auth token`, which works on a
|
|
21
|
+
laptop after `npx decocms auth login` but not in CI.
|
|
22
|
+
|
|
23
|
+
## Which commands need what
|
|
24
|
+
|
|
25
|
+
| Command | `DECO_SITE` | Token |
|
|
26
|
+
|---|---|---|
|
|
27
|
+
| `deco schema`, `deco schema --check`, `deco content` | no | no |
|
|
28
|
+
| `deco check` (production) | yes (else it checks local `.deco/blocks`) | no |
|
|
29
|
+
| `deco check --revision` | yes | no |
|
|
30
|
+
| `deco pull`, `deco diff` (production) | yes | no |
|
|
31
|
+
| `deco pull --draft`, `deco diff --draft`, `deco check --draft`, `deco push`, `deco publish`, `deco drafts`, `deco releases`, `deco schema push` | yes | yes |
|
|
32
|
+
|
|
33
|
+
## The production pipeline
|
|
34
|
+
|
|
35
|
+
```text
|
|
36
|
+
pull request: deco schema --check
|
|
37
|
+
production: install -> deco schema --check -> deco check -> deploy -> deco schema push
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
- `deco schema --check` fails when the committed schema doesn't match the code.
|
|
41
|
+
- `deco check` checks the **live content** against the **new code**, before the deploy. It catches a
|
|
42
|
+
removed block type, a renamed field or a newly required field while production still runs the old
|
|
43
|
+
code.
|
|
44
|
+
- `deco schema push` runs **after** the deploy succeeds, so Studio's forms never describe code that
|
|
45
|
+
isn't live, and only on production. A preview deploy that pushes would let editors save content the
|
|
46
|
+
live code can't render.
|
|
47
|
+
|
|
48
|
+
GitHub Actions and other platforms: [schema.md](./schema.md#step-5-push-it-on-every-production-deploy).
|
|
49
|
+
|
|
50
|
+
A content publish from Studio can also break the next deploy's `deco check` (an editor saves something
|
|
51
|
+
the next code rejects). That is the gate working: fix the content in a draft, or the code.
|
|
52
|
+
|
|
53
|
+
## Changes that touch both code and content
|
|
54
|
+
|
|
55
|
+
**Content needs new code** (a new section, a new field):
|
|
56
|
+
|
|
57
|
+
1. Merge and deploy the code. The pipeline pushes the schema.
|
|
58
|
+
2. Edit in Studio, or `deco push --draft=<name>`.
|
|
59
|
+
3. `deco check --draft=<name>`, preview, `deco publish --draft=<name>`.
|
|
60
|
+
|
|
61
|
+
Publishing first would put content in production that the live code can't resolve.
|
|
62
|
+
|
|
63
|
+
**Code removes or narrows something content uses** (delete a block type, rename a field, make a field
|
|
64
|
+
required):
|
|
65
|
+
|
|
66
|
+
1. Publish content that no longer uses it, or that fills the new field.
|
|
67
|
+
2. Deploy the code. The pipeline's `deco check` passes only after step 1.
|
|
68
|
+
|
|
69
|
+
To find what uses a block type, `deco pull` and grep `.deco/blocks` for `"__resolveType": "<type>"`
|
|
70
|
+
and for references to the saved blocks of that type.
|
|
71
|
+
|
|
72
|
+
**First deploy of a hosted site:** publish a first release before the deploy that sets `site`, or
|
|
73
|
+
every page fails with `LOADER_FAILED`. See [serve-and-studio.md](./serve-and-studio.md#step-3-publish-a-first-release-before-you-deploy-with-site).
|
|
74
|
+
|
|
75
|
+
## Rollback
|
|
76
|
+
|
|
77
|
+
- Code: redeploy the previous build. Then run `deco schema && deco schema push` from that commit so
|
|
78
|
+
Studio's forms match it again.
|
|
79
|
+
- Content: the CLI has no rollback command; roll back in Studio. First run `deco check --revision=<id>`
|
|
80
|
+
against the code that is live.
|
|
81
|
+
See [content-sync.md](./content-sync.md#releases-and-rollback).
|
|
82
|
+
|
|
83
|
+
## Page caches
|
|
84
|
+
|
|
85
|
+
A page cache must key on the content revision, or a publish doesn't show until entries expire. The
|
|
86
|
+
TanStack helper `cacheVersion(cms, buildHash, page.url)` gives `<build>.<revision>`. Cache design is
|
|
87
|
+
`deco-storefront-caching`.
|
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
# Send the schema to Studio
|
|
2
|
+
|
|
3
|
+
Studio draws its editor forms from a schema the site sends. Studio never runs your code. If it has
|
|
4
|
+
no schema for the site, or an old one, its forms are missing or wrong. This page takes a site from
|
|
5
|
+
"Studio asks for the schema" to "every production deploy sends it", with nothing else to read.
|
|
6
|
+
|
|
7
|
+
## What the schema is
|
|
8
|
+
|
|
9
|
+
- `.deco/index.ts` (or `.deco/index.tsx`) default-exports the **block map**: an object of named
|
|
10
|
+
functions. Each function's first parameter type becomes a form.
|
|
11
|
+
- `deco schema` reads that file with the site's own TypeScript and writes `.deco/schema.gen.json`.
|
|
12
|
+
The file declares `"blocksMajor": 8`. Studio treats a site as v8 only from that field.
|
|
13
|
+
- `deco schema push` uploads that file to Studio for the site named by `DECO_SITE`.
|
|
14
|
+
|
|
15
|
+
How a Props type maps to fields (JSDoc tags, widgets, shapes that break a form) is the
|
|
16
|
+
`deco-cms-schema` skill.
|
|
17
|
+
|
|
18
|
+
## Step 1: generate it
|
|
19
|
+
|
|
20
|
+
Requirements: `@decocms/blocks` 8 and `typescript` (a peer dependency) installed in the site.
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
npx deco schema
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
On success it prints one line:
|
|
27
|
+
|
|
28
|
+
```text
|
|
29
|
+
wrote .deco/schema.gen.json from index.ts (12 sections, 3 loaders, 0 matchers, 2 pages, 1 content types)
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
(`unchanged` instead of `wrote` when the file was already up to date.) Commit
|
|
33
|
+
`.deco/schema.gen.json`.
|
|
34
|
+
|
|
35
|
+
If the schema has errors, the file is **not written**, so the committed file never holds a half-right
|
|
36
|
+
form. Fix the errors it prints and run it again. Common lines:
|
|
37
|
+
|
|
38
|
+
| Message | Fix |
|
|
39
|
+
|---|---|
|
|
40
|
+
| `no .deco/ found from <dir>; run inside your app or pass --root` | Run from the app folder, or `--root <dir>` |
|
|
41
|
+
| `no .deco/index.ts (or .deco/index.tsx) in <root>; it holds your block map` | Create the block map |
|
|
42
|
+
| `.deco/index.ts: no default export; export your block map as the default` | `export default { … } satisfies Blocks` |
|
|
43
|
+
| `.deco/index.ts: "<key>" isn't a function` | Every value in the map must be a function |
|
|
44
|
+
| `deco schema reads your types with TypeScript, which isn't installed: …` | Add `typescript` to devDependencies |
|
|
45
|
+
| warning `"<key>": its props are typed any, so its form is empty` | Type the first parameter |
|
|
46
|
+
| warning `"<key>": returns any, so it isn't offered for any field` | Type the return value |
|
|
47
|
+
| warning `"<key>": its first parameter isn't an object of props, so its form is empty` | Take one props object |
|
|
48
|
+
| `"<key>": has a "path" field but its type doesn't extend Route (name: string; path: string)` | A `path` field makes a block routable: give its type `name` and `path`, or rename the field |
|
|
49
|
+
|
|
50
|
+
Run `deco schema` before `dev` and `build`, so the file follows the code:
|
|
51
|
+
|
|
52
|
+
```json
|
|
53
|
+
{
|
|
54
|
+
"scripts": {
|
|
55
|
+
"predev": "deco schema",
|
|
56
|
+
"prebuild": "deco schema"
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`deco schema --watch` regenerates on every `.ts`/`.tsx` change (it skips `node_modules`, `dist`,
|
|
62
|
+
`.git*` and `*.gen.ts`, and also watches files outside the root that the block map imports, such as
|
|
63
|
+
monorepo packages). Stop it with ctrl-c.
|
|
64
|
+
|
|
65
|
+
## Step 2: tell the CLI which site
|
|
66
|
+
|
|
67
|
+
The CLI reads `DECO_SITE`, first match wins:
|
|
68
|
+
|
|
69
|
+
1. the environment;
|
|
70
|
+
2. `.env`, then `.dev.vars`, in the folder that contains `.deco/`;
|
|
71
|
+
3. `vars.DECO_SITE` in `wrangler.jsonc`, `wrangler.json`, then `wrangler.toml` (the `[vars]` table or
|
|
72
|
+
a top-level inline `vars = { … }`), same folder.
|
|
73
|
+
|
|
74
|
+
The value is Studio's site name: letters, digits, `.`, `_`, `-`, starting with a letter or digit.
|
|
75
|
+
Studio finds the organization from the site; the CLI never takes one. A `DECO_SITE` committed in
|
|
76
|
+
`wrangler.jsonc` `vars` (or another file in the list) is found in CI too, with no extra setup.
|
|
77
|
+
|
|
78
|
+
Missing everywhere: exit 64 with
|
|
79
|
+
`no Studio site: set DECO_SITE in the environment, or in <root>'s .env, .dev.vars, or vars.DECO_SITE of wrangler.jsonc, wrangler.json or wrangler.toml (looked in that order)`.
|
|
80
|
+
|
|
81
|
+
## Step 3: a token
|
|
82
|
+
|
|
83
|
+
The CLI sends `Authorization: Bearer <token>` to Studio. It takes the token from:
|
|
84
|
+
|
|
85
|
+
1. `DECO_TOKEN`, when set (use a Studio API key; this is the CI path);
|
|
86
|
+
2. else the output of `npx decocms auth token --target=<DECO_STUDIO_URL>` (Studio CLI's session; the
|
|
87
|
+
CLI has no login of its own). Log in once with `npx decocms auth login --target=https://studio.decocms.com`.
|
|
88
|
+
`deco login` prints that command.
|
|
89
|
+
|
|
90
|
+
No token: exit 3, `not logged in to https://studio.decocms.com; run: npx decocms auth login --target=https://studio.decocms.com`.
|
|
91
|
+
A token Studio rejects: exit 3, `Studio answered 401: … (check DECO_TOKEN, or log in again with npx decocms auth login)`.
|
|
92
|
+
A 403 is also exit 3: Studio refused the token for this site.
|
|
93
|
+
|
|
94
|
+
`DECO_STUDIO_URL` changes the Studio API base (default `https://studio.decocms.com`). Leave it unset
|
|
95
|
+
unless you run a local or staging Studio.
|
|
96
|
+
|
|
97
|
+
## Step 4: push it
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
npx deco schema push
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
It reads `.deco/schema.gen.json` as it is on disk (it does not regenerate it) and sends it to Studio.
|
|
104
|
+
Success:
|
|
105
|
+
|
|
106
|
+
```text
|
|
107
|
+
pushed .deco/schema.gen.json (a v8 schema)
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
`(not a v8 schema)` means the file has no `"blocksMajor": 8`: an older generator wrote it. Run
|
|
111
|
+
`deco schema` again, commit, push again.
|
|
112
|
+
|
|
113
|
+
| Message | Exit | Fix |
|
|
114
|
+
|---|---|---|
|
|
115
|
+
| `no .deco/schema.gen.json; run deco schema first` | 1 | Run `deco schema` |
|
|
116
|
+
| `.deco/schema.gen.json: invalid JSON: …` | 1 | Regenerate it |
|
|
117
|
+
| `deco schema push takes no --watch or --check` | 64 | Drop the flag |
|
|
118
|
+
| `Studio (…) unreachable (…)` / `timed out` | 4 | Network; retry |
|
|
119
|
+
|
|
120
|
+
Reload Studio. The forms now follow the pushed schema.
|
|
121
|
+
|
|
122
|
+
## Step 5: push it on every production deploy
|
|
123
|
+
|
|
124
|
+
Studio should describe the code that is live. So push from the job that deploys production, after
|
|
125
|
+
the deploy succeeds, and never from preview branches. In pull requests, check that the committed file
|
|
126
|
+
is current instead.
|
|
127
|
+
|
|
128
|
+
GitHub Actions, as a sketch (adapt the install and deploy steps to the site):
|
|
129
|
+
|
|
130
|
+
```yaml
|
|
131
|
+
# .github/workflows/deploy.yml
|
|
132
|
+
on:
|
|
133
|
+
push:
|
|
134
|
+
branches: [main]
|
|
135
|
+
jobs:
|
|
136
|
+
deploy:
|
|
137
|
+
runs-on: ubuntu-latest
|
|
138
|
+
env:
|
|
139
|
+
DECO_TOKEN: ${{ secrets.DECO_TOKEN }} # a Studio API key
|
|
140
|
+
# DECO_SITE: my-store # only if it isn't in wrangler.* vars or .env
|
|
141
|
+
steps:
|
|
142
|
+
- uses: actions/checkout@v4
|
|
143
|
+
- run: npm ci
|
|
144
|
+
- run: npx deco schema --check # committed file matches the code
|
|
145
|
+
- run: npx deco check # live content fits this code
|
|
146
|
+
- run: npm run deploy # your deploy
|
|
147
|
+
- run: npx deco schema push # Studio's forms follow what just went live
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
```yaml
|
|
151
|
+
# pull requests
|
|
152
|
+
- run: npx deco schema --check
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
`deco schema --check` writes nothing. It exits 1 when the file is missing or stale and prints what
|
|
156
|
+
moved, for example `sections: new in code: hero` or `2 schema definitions changed (fields or
|
|
157
|
+
choices)`, then `Run \`deco schema\` and commit .deco/schema.gen.json.` It exits 0 with
|
|
158
|
+
`.deco/schema.gen.json is up to date with index.ts`.
|
|
159
|
+
|
|
160
|
+
If the deploy runs somewhere else (Cloudflare Workers Builds, a hosting control plane), run
|
|
161
|
+
`deco schema push` in that platform's production deploy command after the deploy, with `DECO_TOKEN`
|
|
162
|
+
as a secret build variable. Where deco's hosting keeps env vars and secrets is in
|
|
163
|
+
`deco-control-plane-ops` (decocms/skills). The ordering with `deco check` and `deco publish` is in
|
|
164
|
+
[deploy.md](./deploy.md).
|
|
165
|
+
|
|
166
|
+
## Checklist
|
|
167
|
+
|
|
168
|
+
- [ ] `typescript` installed; `deco schema` prints `wrote` or `unchanged`
|
|
169
|
+
- [ ] `.deco/schema.gen.json` committed, with `"blocksMajor": 8`
|
|
170
|
+
- [ ] `DECO_SITE` resolvable from the app folder
|
|
171
|
+
- [ ] `deco schema push` prints `(a v8 schema)`
|
|
172
|
+
- [ ] Production deploy job runs `deco schema push` with `DECO_TOKEN` from secrets
|
|
173
|
+
- [ ] Pull requests run `deco schema --check`
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
# Connect a site to deco Studio (and what happened to `deco serve`)
|
|
2
|
+
|
|
3
|
+
This page takes a v8 site from "Studio can't edit it" to "editors change content in Studio, preview
|
|
4
|
+
it, and publish it", with nothing else to read.
|
|
5
|
+
|
|
6
|
+
## If Studio asks you to connect `deco serve`
|
|
7
|
+
|
|
8
|
+
`deco serve` served `.deco/` from your working tree to Studio over a local endpoint. It shipped in
|
|
9
|
+
`@decocms/blocks` 8.1 through 8.9.x. **It was removed in 8.10.0**, when content moved to Studio's
|
|
10
|
+
hosted CMS on the CDN. On 8.10+:
|
|
11
|
+
|
|
12
|
+
```text
|
|
13
|
+
$ npx deco serve
|
|
14
|
+
unknown command "serve"
|
|
15
|
+
…
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
(exit 64). Check the installed version with `npm ls @decocms/blocks`. `npx deco --help` lists the
|
|
19
|
+
commands this version has.
|
|
20
|
+
|
|
21
|
+
- **On 8.10 or newer:** there is nothing to run on your machine. Studio edits hosted drafts, and the
|
|
22
|
+
site reads them from the CDN. "Connecting" is Steps 1 to 5 below.
|
|
23
|
+
- **On 8.9.x or older:** upgrade `@decocms/blocks` (and the binding, `@decocms/tanstack` or
|
|
24
|
+
`@decocms/nextjs`, at the same version), then do Steps 1 to 5. This skill doesn't document the old
|
|
25
|
+
`deco serve` flags.
|
|
26
|
+
- The error `the endpoint speaks an older deco-content than this client needs (… or newer): update
|
|
27
|
+
@decocms/blocks (8.2.0 or newer) where the endpoint runs` comes from the content protocol client
|
|
28
|
+
when it reaches an older endpoint, such as an 8.1.x `deco serve`. Same fix: upgrade.
|
|
29
|
+
|
|
30
|
+
## Step 1: the site reads hosted content
|
|
31
|
+
|
|
32
|
+
```ts
|
|
33
|
+
// src/cms.ts
|
|
34
|
+
import { createCMS } from "@decocms/blocks";
|
|
35
|
+
import blocks from "../.deco";
|
|
36
|
+
|
|
37
|
+
export const cms = createCMS({ blocks, site: "my-store" });
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
- `site` is Studio's site name. `@decocms/blocks` reads no environment variable: the site passes the
|
|
41
|
+
value, as a literal or from its own config. The CLI finds the same name in `DECO_SITE` (see
|
|
42
|
+
[schema.md](./schema.md), Step 2), so keep the two equal.
|
|
43
|
+
- Leave `content` out. Passing both `site` and `content` is a `TypeError`.
|
|
44
|
+
- A site moving from bundled content (`createCMS({ blocks, content })` with `.deco/blocks.gen.ts`)
|
|
45
|
+
drops `content`, the import of the generated module, and `deco content` from its scripts.
|
|
46
|
+
|
|
47
|
+
How the binding wires `cms` into routes and the worker is in `deco-tanstack-site` /
|
|
48
|
+
`deco-nextjs-site`.
|
|
49
|
+
|
|
50
|
+
## Step 2: send the schema
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
npx deco schema && npx deco schema push
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Without it, Studio has no forms. Tokens, errors and CI wiring: [schema.md](./schema.md).
|
|
57
|
+
|
|
58
|
+
## Step 3: publish a first release, before you deploy with `site`
|
|
59
|
+
|
|
60
|
+
With `site` set, the site has no content until a release exists. The first request on a site whose
|
|
61
|
+
`latest.json` is missing (never published) fails with `LOADER_FAILED` (cause
|
|
62
|
+
`ContentUnavailableError`); the SDK never serves an empty site. So publish first:
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
# .deco/blocks holds the content you have (bundled before, or written by hand)
|
|
66
|
+
npx deco push --draft=initial # every file is new: all of them go to the draft
|
|
67
|
+
npx deco check --draft=initial # the draft against the code
|
|
68
|
+
npx deco publish --draft=initial # the first release
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Then remove `.deco/blocks/` from git and add `.deco/blocks/` and `.deco/pull.json` to `.gitignore`.
|
|
72
|
+
`deco pull` fills the folder again when you need it. A push must fit one save (500 blocks, 8 MiB,
|
|
73
|
+
1 MiB per block); for a bigger site see [content-sync.md](./content-sync.md#push).
|
|
74
|
+
|
|
75
|
+
A site with no content yet can skip this only if it creates its first blocks in Studio and publishes
|
|
76
|
+
before the deploy that sets `site`.
|
|
77
|
+
|
|
78
|
+
## Step 4: the page accepts Studio's frame
|
|
79
|
+
|
|
80
|
+
Studio opens the site in an iframe and loads its editor code into the page through the **Studio
|
|
81
|
+
channel**, a small inline script the bindings put on every page:
|
|
82
|
+
|
|
83
|
+
- **TanStack** (`@decocms/tanstack`): `DecoDocument` in `__root.tsx` (or `<DecoPreview site=… />` in
|
|
84
|
+
a document of your own) mounts the bridge, the channel and the draft badge. `createDecoWorker` adds
|
|
85
|
+
Studio's origins to `frame-ancestors` and `script-src` and sends no `X-Frame-Options`.
|
|
86
|
+
- **Next.js** (`@decocms/nextjs`): `<StudioBridge site="my-store" />` in the root layout's `<body>`.
|
|
87
|
+
A site that writes its own CSP passes it through `withStudioCsp(directives)`. Render
|
|
88
|
+
`<StudioPage pathTemplate={match.entry.path} />` on CMS pages so Studio opens the right page.
|
|
89
|
+
|
|
90
|
+
The page trusts an exact list of Studio origins: the binding's `studioOrigins` option, else the
|
|
91
|
+
`DECO_STUDIO_ORIGIN` env var (comma-separated), else `https://studio.decocms.com` and
|
|
92
|
+
`https://studio-stg.decocms.com`. A page framed by any other origin does nothing. For a Studio you
|
|
93
|
+
run locally, set `DECO_STUDIO_ORIGIN=http://localhost:3000` (its origin) for the site, and
|
|
94
|
+
`DECO_STUDIO_URL` to its API base for the CLI.
|
|
95
|
+
|
|
96
|
+
## Step 5: previews, in Studio and on your machine
|
|
97
|
+
|
|
98
|
+
Studio saves edits into a draft. A draft is seen through a link: `?__draft=<pointer>` on any page.
|
|
99
|
+
The CLI prints it:
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
npx deco drafts url my-change
|
|
103
|
+
# a preview URL, or a pointer plus:
|
|
104
|
+
# (the site has no preview address in Studio: open the site with ?__draft=<this pointer>)
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
A draft link previews only on allowed hosts: the ones Studio writes into the release
|
|
108
|
+
(`previewHosts` in `latest.json`) plus `createCMS({ preview: { hosts } })`. On any other host the link
|
|
109
|
+
silently renders the published release. That is the usual reason a draft "shows production" on
|
|
110
|
+
`localhost`. Allow it in dev:
|
|
111
|
+
|
|
112
|
+
```ts
|
|
113
|
+
createCMS({
|
|
114
|
+
blocks,
|
|
115
|
+
site: "my-store",
|
|
116
|
+
// Vite dev; on Next.js test process.env.NODE_ENV === "development"
|
|
117
|
+
...(import.meta.env.DEV ? { preview: { hosts: ["localhost"] } } : {}),
|
|
118
|
+
});
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
A host pattern without a port matches any port. Before the first publish, or for a release published
|
|
122
|
+
before Studio wrote `previewHosts`, every host previews.
|
|
123
|
+
|
|
124
|
+
Local dev reads content from the CDN like production. Editing `.deco/blocks` locally changes nothing
|
|
125
|
+
on the page until you `deco push` it to a draft and open the draft link.
|
|
126
|
+
|
|
127
|
+
## Diagnose a site Studio can't edit
|
|
128
|
+
|
|
129
|
+
| Symptom | Check | Fix |
|
|
130
|
+
|---|---|---|
|
|
131
|
+
| Studio says to send the schema, or forms are empty or stale | `npx deco schema push` prints `(a v8 schema)` | [schema.md](./schema.md) |
|
|
132
|
+
| Page in Studio is blank or refuses to frame | `curl -sI <url>`: `content-security-policy` has `frame-ancestors` with `https://studio.decocms.com`; no `x-frame-options` | Use the binding's worker or `withStudioCsp`; remove your own `X-Frame-Options` |
|
|
133
|
+
| Page shows, but no section outlines or live updates | Page HTML has a `<script data-deco-studio-channel …>`; its `data-studio-origins` lists Studio's origin | Mount `DecoDocument` / `DecoPreview` / `StudioBridge`; fix `studioOrigins` or `DECO_STUDIO_ORIGIN`; add the CSP `nonce` |
|
|
134
|
+
| Every page errors with `LOADER_FAILED` | `https://delivery.decocms.com/sites/<site>/latest.json` returns 404 | Publish a first release (Step 3) |
|
|
135
|
+
| Draft link shows the published content | Host not in the preview hosts | `preview.hosts` (Step 5) |
|
|
136
|
+
| Draft link shows the release and a notice that the draft can't be read | The draft no longer exists or can't be read | Get a fresh link with `deco drafts url <name>` |
|
|
137
|
+
| `/live/*`, `/.decofile`, `/deco/*` answer 404 | Expected on v8 (TanStack worker). `/deco/_liveness` answers `OK` | Remove v7 admin wiring; see `deco-v7-to-v8-migration` |
|
|
138
|
+
| A CLI command exits 3 | No token, or Studio refused it | [schema.md](./schema.md), Step 3 |
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: deco-storefront-caching
|
|
3
|
+
description: "Edge caching and origin egress for storefronts on @decocms/blocks 8. Covers the site-owned pageCache on createDecoWorker from @decocms/tanstack/worker (isCacheable, cacheVersion keyed by build and content revision, assignmentsKey, segmentKey and the __cseg token, serverFnPagePath, DEGRADED_HEADER, markPrivate, drafts and old releases never cached, the purge route), cache-key rules (key only on what changes the payload, strip tracking params, segment without splitting for nothing, never store non-200, degraded or empty pages, one upstream call per request), the traps that kill hit rate or raise egress (Set-Cookie, tracking-param poisoning, region and device splits, Vary, redirects, hidden variants, payload bloat), the Next.js equivalents in @decocms/nextjs/proxy, and verification with curl, X-Cache headers, scripts/html-anatomy.mjs and Playwright guardrails. Load it when the hit rate drops, egress or upstream calls rise, a page is never cached, or a change touches the worker entry or the cache key."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Storefront caching and egress (v8)
|
|
7
|
+
|
|
8
|
+
On v8 the framework caches no page. `createDecoWorker` from `@decocms/tanstack/worker` decides
|
|
9
|
+
drafts, the visitor and each test's assignment, then hands every cacheable request to the site's
|
|
10
|
+
own `pageCache`. The cache key, the TTLs and the purge route live in the site's
|
|
11
|
+
`src/worker-entry.ts`, usually a copy of the repo's example. So when the hit rate drops, the cause
|
|
12
|
+
is almost always in site code: the key, a cookie, a header, or a page that should not be stored.
|
|
13
|
+
|
|
14
|
+
Read this when you arrived with a number (egress up, hit rate down, upstream bill up) or with a
|
|
15
|
+
change to the worker entry, a loader on a cacheable page, or the segment.
|
|
16
|
+
|
|
17
|
+
## When to load what
|
|
18
|
+
|
|
19
|
+
| Reference | Load it when |
|
|
20
|
+
|---|---|
|
|
21
|
+
| [`references/worker-page-cache.md`](./references/worker-page-cache.md) | Wiring or changing `pageCache`: what the worker does for you, the helpers, profiles and TTLs, stale serving, server functions and `__cseg`, the purge route |
|
|
22
|
+
| [`references/cache-keys.md`](./references/cache-keys.md) | Writing or reviewing the key or `buildSegment`; a page cached empty or broken; deduping upstream calls; an upstream data cache |
|
|
23
|
+
| [`references/egress-traps.md`](./references/egress-traps.md) | Hit rate is low or egress is high and you need the list of causes, in the order to check them |
|
|
24
|
+
| [`references/verification.md`](./references/verification.md) | Proving a fix: curl probes, the headers to read, `scripts/html-anatomy.mjs`, telemetry |
|
|
25
|
+
| [`references/perf-guardrails-e2e.md`](./references/perf-guardrails-e2e.md) | Locking the gains in CI with a Playwright spec and probes |
|
|
26
|
+
| [`references/nextjs.md`](./references/nextjs.md) | The site runs on `@decocms/nextjs` instead of the TanStack worker |
|
|
27
|
+
| [`references/case-study.md`](./references/case-study.md) | You want a worked example of an egress audit, with measured numbers and two reverts |
|
|
28
|
+
|
|
29
|
+
`scripts/html-anatomy.mjs` (Node 18+, no dependencies) shows where the bytes of a page go:
|
|
30
|
+
`node .agents/skills/deco-storefront-caching/scripts/html-anatomy.mjs https://SITE/category`.
|
|
31
|
+
|
|
32
|
+
## The model in five lines
|
|
33
|
+
|
|
34
|
+
1. A request reaches `pageCache` only if `isCacheable` accepts it: a `GET` of the current release,
|
|
35
|
+
no draft signal, no `Authorization`, not `/_build`, not `vite dev`. Everything else skips it.
|
|
36
|
+
2. Every key carries `cacheVersion(cms, __BUILD_HASH__, url)`: `<build>.<content revision>`. A
|
|
37
|
+
deploy or a publish moves every page to new entries. Nothing to purge after a publish.
|
|
38
|
+
3. Every key carries `assignmentsKey(page.assignments)`: the tests on and the campaigns running,
|
|
39
|
+
never the visitor id. Visitors on the same side of every test share one entry.
|
|
40
|
+
4. The worker adds the visitor's first-visit cookie after `pageCache` answers, so a stored copy
|
|
41
|
+
never carries it. Any other `Set-Cookie` outside the example's `SAFE_COOKIES` makes it treat
|
|
42
|
+
the response as private and not store it.
|
|
43
|
+
5. A response that sets no `CDN-Cache-Control` leaves the worker with `CDN-Cache-Control: no-store`.
|
|
44
|
+
The example lets the CDN keep only server-function data whose `__cseg` token matches.
|
|
45
|
+
|
|
46
|
+
## Order of work for "egress is high"
|
|
47
|
+
|
|
48
|
+
1. Get the numbers first: which paths, how many bytes, hit rate per path (`deco-performance-audit`
|
|
49
|
+
in decocms/skills, or the `http.server.request.duration` metric by `cache` and `http.route`).
|
|
50
|
+
2. Pages that are never stored (`X-Cache: BYPASS`) cost on every visit. Fix those first.
|
|
51
|
+
3. Then keys that split for nothing (tracking params, region, device, assignments).
|
|
52
|
+
4. Then the size of what is stored (a fat HIT is still egress).
|
|
53
|
+
5. Lock it in with the Playwright guardrails, then watch telemetry for 24 hours.
|
|
54
|
+
|
|
55
|
+
## Related skills
|
|
56
|
+
|
|
57
|
+
- `deco-tanstack-site`: the worker entry, `createStart` with `decoServerFnFetch`, the router.
|
|
58
|
+
- `deco-nextjs-site`: Next.js setup; its caching reference covers ISR in depth.
|
|
59
|
+
- `deco-variants`: keeping variant pages cacheable, client-side personalization.
|
|
60
|
+
- `deco-storefront-performance`: payload trimming, duplicate upstream calls, Worker memory.
|
|
61
|
+
- `deco-apps`: which commerce responses are shopper-invariant and safe to cache.
|
|
62
|
+
- `deco-go-live`: the cache checks in the cutover list.
|
|
63
|
+
- `deco-v7-to-v8-migration`: moving v7's `createDecoWorkerEntry`, `buildSegment` and cache
|
|
64
|
+
profiles into the worker entry (its caching-and-privacy reference).
|
|
65
|
+
- decocms/skills: `deco-performance-audit` (CDN numbers), `deco-bot-management` and
|
|
66
|
+
`deco-cloudflare-waf` (crawler traffic), `deco-e2e-testing` (Playwright harness).
|
|
67
|
+
- Runbook: `docs/runbooks/cache-hit-drop.md` in this repo, for the cache-hit-drop alert.
|