A calm place to write long-form, and publish it to the open social web.
skypress.blog/
Document React 18 pin as upstream-driven, with React 19 upgrade path
The react@18.3.1 pin flows from @wordpress/block-editor → @wordpress/element
peer-depping react@^18, which reflects Gutenberg reverting its React 19
upgrade (WordPress/gutenberg#78940, merged 2026-06-04). Record the cause and
the upgrade trigger so the bump can happen routinely once Gutenberg re-lands
React 19.
- AGENTS.md: expand hard-constraint #1 with the upstream cause and trigger.
- Decision 0001: add a dated addendum with the React 19 upgrade checklist.
author
Jeremy Herve
date
(Jun 18, 2026, 5:28 PM +0200)
commit
1c4b87e2
1c4b87e2271e79cbc52cca73bca7accb3c088a9c
parent
1bcd127b
1bcd127b6e0d08fa2c4d70b88039c9dcfe59493b
+35
-2
+8
-2
AGENTS.md
+8
-2
AGENTS.md
···
19
19
20
20
## Hard constraints (learned the hard way — see decisions)
21
21
22
-
1. **React 18 only.** `@wordpress/block-editor@15.x` peer-depends on `react@^18`. Do not
23
-
introduce React 19. (Decision 0001)
22
+
1. **React 18 only.** `@wordpress/block-editor@15.x` → `@wordpress/element` peer-depends on
23
+
`react@^18`. Do not introduce React 19. (Decision 0001) — This pin is *upstream-driven*:
24
+
Gutenberg tried React 19 and reverted it (WordPress/gutenberg#78940, merged 2026-06-04;
25
+
plugins bundling a legacy `react/jsx-runtime` tripped React 19's element-symbol check,
26
+
react.dev/errors/525). **Upgrade trigger:** when Gutenberg re-lands React 19 and
27
+
`@wordpress/element`'s peer range opens to `^19`, bump `react`/`react-dom` and drop the
28
+
`react`/`react-dom` keys from `overrides` in `package.json`. It's a normal version bump,
29
+
not an architecture change (Decision 0021).
24
30
2. **SkyPress depends on `@wordpress/block-editor` and friends directly** at the current
25
31
release line; there is **no `@wordpress/*` `overrides` map** (only `react`/`react-dom`
26
32
stay pinned). Depending directly, the tree resolves to a single coherent copy of every
+27
docs/decisions/0001-framework-and-stack.md
+27
docs/decisions/0001-framework-and-stack.md
···
89
89
that array round-trips to HTML via the shared `@wordpress/blocks`, and the production
90
90
build reports the editor JS confined to the authoring route. See
91
91
`docs/specs/sp0-foundations-editor-spike.md`.
92
+
93
+
## Addendum (2026-06-18) — React 18 pin is upstream-driven; upgrade path
94
+
95
+
The React 18 lock no longer comes from `isolated-block-editor`'s bundled versions (that
96
+
coupling is gone — see Decision 0021). It now comes straight from
97
+
`@wordpress/block-editor@15.x` → `@wordpress/element`, which peer-depends on `react@^18`.
98
+
That, in turn, reflects **Gutenberg upstream**: Gutenberg attempted to move to React 19 and
99
+
**reverted it** in [WordPress/gutenberg#78940](https://github.com/WordPress/gutenberg/pull/78940)
100
+
(merged 2026-06-04). The blocker was the React element-symbol change — plugins bundling a
101
+
legacy `react/jsx-runtime` emit `$$typeof: Symbol.for('react.element')`, which React 19's
102
+
runtime check rejects (`Symbol.for('react.transitional.element')`,
103
+
[react.dev/errors/525](https://react.dev/errors/525)); React 19's `renameElementSymbol`
104
+
escape hatch was removed.
105
+
106
+
**When can we upgrade React?** When Gutenberg re-lands React 19 and the
107
+
`@wordpress/element` we depend on opens its peer range to include `^19`. At that point the
108
+
upgrade is a routine version bump:
109
+
110
+
1. Bump `react` / `react-dom` to 19.x in `package.json`.
111
+
2. Drop the `react` / `react-dom` keys from `overrides` (and the matching note on the
112
+
`comment:overrides` line).
113
+
3. Bump the `@wordpress/*` line to the React-19-capable release, run `npm dedupe`, and
114
+
re-check the `resolve.dedupe` backstop (per Decision 0021).
115
+
4. Re-verify the editor island boots with no "invalid hook call" / duplicate-React errors.
116
+
117
+
No architecture change is needed — Astro islands + the single-copy dedupe strategy already
118
+
accommodate either React major. Track the upstream re-attempt to know when this unblocks.