Zum Hauptinhalt springen

React 19 Compatibility Notes

Status​

  • Peer compatibility declared — under verification.
  • Date: 2026-04-24.
  • Branch / PR: chore/react-19-compatibility-and-legacy-links.

This document records exactly what the React-19 peer update does and what it deliberately does not claim. It is intentionally narrow. A React-19 runtime smoke test against a real consumer app lives in a later PR.

What changed​

  • React peer ranges in every library package under packages/@smolitux/* were updated from ^17.0.0 || ^18.0.0 to ^17.0.0 || ^18.0.0 || ^19.0.0 for both react and react-dom. Affected: ai, blockchain, charts, community, core, federation, layout, media, resonance, theme, utils, voice-control.
  • @smolitux/testing already declared react >=17.0.0 / react-dom >=17.0.0 in its peer range, so React 19 is already admitted there. No change needed.
  • packages/playground/src/package.json is a local example app (not a publishable library), and is left on react ^18.2.0 / react-dom ^18.2.0 to match its existing dev-dependency story.
  • Root-level devDependencies.react-test-renderer stays on ^18.3.1. Tests continue to run against the React 18 baseline in this PR.
  • devDependencies.@types/react and devDependencies.@types/react-dom across all packages stay on ^18.0.0. Bumping the type packages to include React 19 types is a separate, larger change that is explicitly out of scope here.
  • Legacy repository links in active documentation were updated from EcoSphereNetwork/smolitux-ui → Modularium/smolitux-ui and from ecospherenetwork.github.io/smolitux-ui → modularium.github.io/smolitux-ui. Archive paths (docs/_archive/**, docs/wiki/legacy/**, scripts/legacy/**, AGENTS.old*.md) were intentionally left unchanged.

What this does not mean​

  • Not a full React 19 certification. The peer range admits React 19, but no automated run of the test suite against React 19 was performed in this PR.
  • No per-component React 19 audit. Individual components have not been inspected for known React-19 incompatibilities (e.g. changes in useId, Suspense boundaries, ref as a prop, ownerDocument behaviour inside portals).
  • Storybook / test baseline remains React 18. .storybook/ and jest.config.js dependencies have not been migrated; the toolchain still resolves React 18.x during local development and CI.
  • SSR safety is not certified here. No per-component SSR import-time audit was performed. Portal-based components may still reference window / document unguarded.

Verified in this PR​

  • package.json JSON validity was verified by parsing every packages/@smolitux/*/package.json with python3 json.load after the peer-range update.
  • grep confirms no active documentation path still references EcoSphereNetwork/smolitux-ui or ecospherenetwork.github.io/smolitux-ui. Every remaining hit lives under docs/_archive/**, docs/wiki/legacy/**, scripts/legacy/**, or AGENTS.old*.md.
  • modularium.github.io/smolitux-ui/ serves HTTP 200; the old ecospherenetwork.github.io/smolitux-ui/ now returns 404. Active doc links point at the live host.

See the PR description for concrete npm install / npm test / npm run build / npm run lint results and any tool-side failures that were found.

Still open​

  • React 19 runtime smoke with a real test app (candidate: packages/playground/ or a fresh Next.js 15 / Vite sandbox).
  • Storybook run under React 19 — the current Storybook setup uses @storybook/react-webpack5 with React 18 peer expectations.
  • Per-component audit for portal components: Dialog, Modal, Drawer, Tooltip, Toast, Dropdown, Popover.
  • SSR import-safety audit: verifying every component is safe to import from a server component in Next.js 14 / 15 without touching window / document at module scope.
  • Release-tag / changelog alignment: CHANGELOG.md currently documents up to 0.3.7, but the last GitHub Release is v0.2.2. Consumers cannot currently pin a 0.3.x git tag.
  • @types/react / @types/react-dom upgrade to include React 19 types once the toolchain is ready.

OceanData relevance​

  • OceanData PR12.x can now plan against declared React 19 peer compatibility more safely than against the previous ^17 || ^18-only range. The OceanData Control Plane is not required to stay on React 18.
  • OceanData still must not hard-pin Smolitux-UI until the release / tag discipline is resolved. As of 2026-04-24, the last GitHub Release is v0.2.2 while CHANGELOG.md has reached 0.3.7. Until a 0.3.x git tag / npm publish lands, a consumer cannot declare a stable Smolitux-UI version.
  • Smolitux-UI is the canonical Web / React component library of the Smolitux ecosystem. OceanData is the data layer, not a design system; OceanData consumes Smolitux-UI, not the other way around. See also ADR-0001 (docs/adr/ADR-0001-smolitux-design-contract.md) — the cross-runtime Smolitux Design Contract that anchors React, Godot/Smolit-Assistant, and other native clients.