Updates and migrations

The update process depends on the installation model. Package consumers update dependency versions; CLI consumers own copied source and decide how to reconcile it with the current registry. Check the component’s import path when you are unsure which model it uses.

Current projects use schemaVersion: 1 in simurgh.json. The CLI automatically adds that version to legacy unversioned configs while preserving their framework and paths. If a config uses a newer schema, upgrade @simurgh-ui/cli; if its schema is otherwise unsupported, create a clean schema 1 config with simurgh init and migrate the reviewed paths. Newly copied component files also record generated-source schema 1, the registry version, framework, and component in their header.

Applications upgrading positioned overlays should also read the overlay positioning migration. It records the supported positioning subset, interaction differences, dependency cleanup, and measured bundle change.

Before updating

1. Commit or otherwise back up application code, simurgh.json, copied components, and local theme changes.
2. Record the current Simurgh versions from the lockfile and the registryVersion from simurgh.json when present.
3. Read the release notes and Changesets for the versions being adopted. Simurgh is pre-release, so minor and patch releases may still require migration work.
4. Update one installation model at a time. Do not overwrite copied source merely because package dependencies changed.

Updating package components

Package components are imported from @simurgh-ui/react, @simurgh-ui/vue, @simurgh-ui/angular, or their component subpaths. Update the adapter and styles together so API and recipe changes remain aligned:

# Replace `react` with `vue` or `angular` for the active adapter.
pnpm update @simurgh-ui/react @simurgh-ui/styles

After updating:

1. Inspect the lockfile and confirm the intended versions were selected.
2. Run type checking and the application’s unit, accessibility, and browser tests.
3. Exercise controlled state, form submission, keyboard navigation, overlays, RTL, and custom theme overrides used by the application.
4. Review bundle output when changing aggregate imports or adopting overlay components.

If an API changed, update application usage rather than editing files inside node_modules. Pin the previous exact version while preparing a larger migration if the application cannot adopt the new API immediately.

Updating CLI-copied components

Copied components are application source. Updating @simurgh-ui/cli does not silently modify them. Use the intended CLI version explicitly when inspecting the registry:

pnpm dlx @simurgh-ui/cli@<version> list
pnpm dlx @simurgh-ui/cli@<version> diff dialog

diff compares the complete local component file with the source generated by that registry. Its exit status is non-zero when a file is missing or differs. A difference is not necessarily an error—it may be an intentional application customization.

For each changed component:

1. Save the local file and identify application-specific behavior, markup, imports, and styles.
2. Generate the newer registry version in a temporary branch or disposable application.
3. Compare the old registry source, the local customized source, and the new registry source as a three-way change.
4. Port upstream accessibility and behavior changes into the local component while preserving intentional customization.
5. Run the component’s application tests and task-based keyboard checks.
6. Update registryVersion in simurgh.json only after the adopted local components have been reviewed against that registry.

Using overwrite safely

pnpm dlx @simurgh-ui/cli@<version> add dialog --overwrite

--overwrite replaces the target component file; it does not merge local edits. Use it only when the exact target is known and either no customization must be preserved or that customization is already recoverable from version control. Inspect git diff immediately after the command and do not combine unrelated component overwrites in one review.

Without --overwrite, add preserves an existing component and reports that it was skipped. This is the safer default for routine registry exploration.

Resolving a diff conflict

When both the application and registry changed the same behavior, resolve the contract before the textual conflict:

• Preserve the newer registry’s roles, accessible naming, keyboard handling, focus management, form value, and disabled-state behavior unless the application has an explicitly tested reason to differ.
• Reapply visual changes through tokens, recipe classes, or stable state hooks where possible. This reduces future source conflicts.
• Reconcile public props, events, inputs, outputs, and slots with every call site before deleting an older local API.
• Keep local application policy—analytics, domain validation, data fetching, or product copy—outside the primitive when it can be composed by a wrapper.

After resolving, run diff again. It may continue to report a difference because maintained local customization is expected; record why that difference exists rather than forcing the file to match.

Switching installation models

Treat switching from copied source to packages, or packages to copied source, as a migration—not an import-only refactor. Compare public APIs and rendered DOM, move styling to the destination model, update every import, and verify form and accessibility behavior before removing the old component. Do not keep both versions mounted for the same control or mix package child parts with a locally copied compound-component root.

Last verified on 2026-08-13 against Simurgh registry 0.1.1.