Skip to content
nexus-dialogs
GitHub npm

Versioning and migrations

How versions are numbered, how to read the CHANGELOG and what to do before and after upgrading. The full policy and what is supported is in Support; this is the practical part.

#How versions are numbered

Semantic versioning is followed (major.minor.patch):

ChangeExampleWhat to expect
Patch1.0.0 → 1.0.1Fixes only. Upgrading is safe
Minor1.0.x → 1.1.0It only adds. (Up to 0.x, a minor could break)
Major1.x → 2.0May break. Whatever is removed was announced as deprecated a minor version earlier

What counts as "breaking" (removing or renaming a public export, changing what a function returns, changing a default value that alters the result, or raising a browser minimum) is in Support.

#How to read the CHANGELOG

Each version in the CHANGELOG (in Spanish) is divided into sections, always in this order:

#Before upgrading

  1. Choose how to pin the version. From 1.0 you can use "nexus-dialogs": "^1.0.0": minor versions and patches do not break. If you prefer that a fresh install never changes on its own, use the exact version, without ^ or ~.
  2. Read "Breaking changes" for every version between yours and the new one, not just the latest.
  3. Search your code for what each change mentions (the function or option name).
  4. Check the types: tsc flags removed or renamed exports and options that changed shape.
  5. Upgrade and run your tests. If you have UI tests, dialogs are native <dialog> elements with data-nexus-dialog, so your selectors should not change.

#What is watched so it doesn't break you

#Known migrations

FromToWhat changesHow to migrate
0.5.x1.0.0Nothing breaks: 1.0.0 only fixes the public API and semantic versioningUpgrade and run your tests
0.4.x0.5.0strictHtml is true by default: string html is shown as textWith your own content, configure({ strictHtml: false }). With outside content, configure({ sanitize: (h) => DOMPurify.sanitize(h) }). Nodes and plain texts don't change

New migrations are added here as they come out. For coming from SweetAlert2 there is a separate guide: Migrate from SweetAlert2.

#When something is going to be removed

A function that is going to be retired keeps working for one full minor version, marked @deprecated in the types (your editor strikes it through) and listed under "Deprecated" in the CHANGELOG with its replacement. It is only removed in the next major version. (In 0.x the notice could last less, but it always appeared under "Breaking changes".)

#If the upgrade breaks something

Go back to the previous version (npm install nexus-dialogs@1.0.0) and open an issue with the version you come from, the one you are going to and a minimal case. If the change was not in "Breaking changes", it is a CHANGELOG error and it gets fixed.