Skip to content
Skills Library
Programming · Conversion & formats

migrate-react-18

/migrate-react-18

Upgrade a consumer project to the latest major @entur/* design system packages. Covers breaking changes (ESM exports, modal, tabs, expand, layout, utils) and verifies the project meets the React 18 minimum. Use when upgrading @entur packages, fixing breakage after updating @entur dependencies, or migrating to the newest design system versions.

Author
entur ↗
Licence
AGPL-3.0
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.

What it does and when to use it

Upgrade a consumer project to the latest major @entur/* design system packages. Covers breaking changes (ESM exports, modal, tabs, expand, layout, utils) and verifies the project meets the React 18 minimum. Use when upgrading @entur packages, fixing breakage after updating @entur dependencies, or migrating to the newest design system versions.

Original author description

Upgrade a consumer project to the latest major @entur/* design system packages. Covers breaking changes (ESM exports, modal, tabs, expand, layout, utils) and verifies the project meets the React 18 minimum. Use when upgrading @entur packages, fixing breakage after updating @entur dependencies, or migrating to the newest design system versions.

How it works

  1. Steps
Original SKILL.md headings · 111 lines, 760 words
SKILL.md preview
---
name: migrate-react-18
description: Upgrade a consumer project to the latest major @entur/* design system packages. Covers breaking changes (ESM exports, modal, tabs, expand, layout, utils) and verifies the project meets the React 18 minimum. Use when upgrading @entur packages, fixing breakage after updating @entur dependencies, or migrating to the newest design system versions.
disable-model-invocation: true
---

# Upgrade @entur/\* packages to latest major versions

The latest major versions of all `@entur/*` packages require React 18 as a minimum. Most consumer projects are already on React 18+ — the main work is handling package-specific breaking changes.

> **Resolving `references/` paths:** if you are reading this over HTTP rather than from an installed skill folder, resolve every `references/<file>` path in this file against `https://raw.githubusercontent.com/entur/design-system/main/skills/migrate-react-18/` — not against the folder of whichever skill linked you here.

## Steps

### 1. Inventory

Scan `package.json` (and monorepo workspace `package.json` files if applicable) for:

- All `@entur/*` packages and their current versions
- Current React and React-DOM versions
- `@testing-library/react` version (if present)
- `tsconfig.json` `jsx` setting

Report what you found before proceeding.

**Done when:** every `@entur/*` package, React version, and testing-library version is listed.

### 2. Check React version

If React is already 18+, skip to step 3.

If React is below 18:

```bash
npm install react@^18 react-dom@^18 @types/react@^18 @types/react-dom@^18
```

Then search for `ReactDOM.render` — replace with `createRoot`:

```tsx
// Before
import ReactDOM from 'react-dom';
ReactDOM.render(<App />, document.getElementById('root'));

// After
import { createRoot } from 'react-dom/client';
const root = createRoot(document.getElementById('root')!);
root.render(<App />);
```

Also search for `ReactDOM.hydrate` — replace with `hydrateRoot` from `react-dom/client`.

If `tsconfig.json` has `"jsx": "react"`, change to `"jsx": "react-jsx"`.

**Done when:** React is 18+ and entry points use the new API (or were already there).

### 3. Upgrade @entur/\* packages

Update all `@entur/*` packages to their latest versions:

```bash
npm install @entur/button@latest @entur/modal@latest ...
```

List every `@entur/*` package in the project and upgrade them all in one command.

**Done when:** all `@entur/*` packages are at their latest versions.

### 4. Fix breaking changes

Load **[references/breaking-changes.md](references/breaking-changes.md)** and work through each section that applies to this project. Only process sections for packages the project actually uses.

The reference covers:

| Package                      | Key changes                                                                                             |
| ---------------------------- | ------------------------------------------------------------------------------------------------------- |
| ESM `exports` (all packages) | Deep `dist/` imports break; built files renamed to `.mjs`/`.cjs`                                        |
| `@entur/modal`               | `onDismiss` required, `<div>` → `<dialog>`, `data-reach-*` selectors gone                               |
| `@entur/tab`                 | `data-reach-*` selectors gone, stricter types, ID format changed, tab/panel index comes from the markup |
| `@entur/expand`              | Content stays in DOM when collapsed; `unmountOnClose` opt-out                                           |
| `@entur/layout` (beta)       | `LayoutProvider` removed; responsive base key `s` → `base`                                              |
| `@entur/utils`               | `useRandomId` deprecated → use React `useId()`                                                          |

For each applicable section: grep for the affected patterns, fix them, and confirm no instances remain.

**Done when:** every pattern listed in breaking-changes.md has been searched for and resolved for each used package.

### 5. Report behavioral changes

After all code changes are applied, inform the user about behavioral differences they should be aware of. Load **[references/behavioral-changes.md](references/behavioral-changes.md)** and present every section relevant to the packages this project uses.

These are changes that require no code fix but alter how the application behaves at runtime, in tests, or during development.

**Done when:** every relevant behavioral change has been communicated to the user.

### 6. Verify

Run the project's build and test suite:

```bash
npm run build
npm test
```

Fix any remaining type errors or test failures. Common issues:

- **Type errors from stricter props** — `@entur/tab` components no longer accept arbitrary props. Remove unknown props.
- **Test failures from ID changes** — Tab/panel IDs now use `useId()` format. Don't match specific ID strings; use `aria-controls`/`aria-labelledby` to find linked elements.
- **All panels render under the first tab** — panels hidden behind a component of your own (an error boundary, a data wrapper, or a component per panel) share one index. Render each panel from `<TabPanels>`, or pass each one an explicit `index` prop. `@entur/tab` logs an error in development when this happens.
- **Panels are off by one** — a component of your own inside `<TabPanels>` takes an index even when it renders no panel, so a heading or layout component shifts every panel after it. Move it out of `<TabPanels>`, or inline it as plain markup.
- **A tab shows the wrong panel** — a `<Tab>` and its `<TabPanel>` sit under different conditions, so a falsy conditional shifts every later index on one side only. Silent when the conditional is mid-list; merely logged when it's last. Put both behind the same condition.
- **Test failures from batched updates** — React 18 batches all state updates. Wrap assertions that depend on intermediate states in `act()` or use `waitFor`.
- **Double renders in dev** — `<StrictMode>` now mounts, unmounts, and re-mounts components. This is expected; fix missing `useEffect` cleanups it reveals.

**Done when:** build succeeds and tests pass.
Files in this package (3)
  • SKILL.md 6 KB
  • references/behavioral-changes.md 6 KB
  • references/breaking-changes.md 15 KB

Versions

The database has no other skills named migrate-react-18.

Database snapshot: 13.11.2026 · package version c503d126642f (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100entur-web-development
    Build React applications with Entur Linje @entur/* component packages. Use when the user is installing, importing, or using any @entur/* package, asking about Entur React components, Entur tokens, Entur CSS variables, Entur design system in a development context, or building web…
  • 100migrate-typography
    Migrate a consumer project to the new Entur typography (`@entur/typography/beta`) and the layout beta spacing scale. Covers the renamed spacing values, text without default spacing and `TextContainer`, renamed and removed variants, new HTML elements, `Label`, quotes, lists, CSS…
  • 95react-modernization
    Upgrade React applications to latest versions, migrate from class components to hooks, and adopt concurrent features. Use when modernizing React codebases, migrating to React Hooks, or upgrading to latest React versions.
  • 100react-modernization
    Upgrade React applications to latest versions, migrate from class components to hooks, and adopt concurrent features. Use when modernizing React codebases, migrating to React Hooks, or upgrading to latest React versions.
  • 95elevenlabs:sdk-migration
    Migrate to the next major version of @elevenlabs/client, @elevenlabs/react, and @elevenlabs/react-native. Use when updating code that uses Conversation, Input, Output, useConversation, ElevenLabsProvider, ConversationProvider, or related APIs from these packages. Also trigger…
  • 100dependency-upgrade
    Upgrade dependencies safely using pnpm catalog, checking for breaking changes, and testing upgrades. Use when updating packages, applying security patches, upgrading major versions, resolving dependency conflicts, or modernizing tech stack.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.