Migration to 1.0.0 Web Components
This guide will help you understand how to transition an existing project from using a beta version of Nord Web Components to using the official 1.0.0 production version.
Updating package.json and dependencies
The first step towards migrating to the latest Nord Web Components is to update package.json
with the necessary dependencies. You should:
- Update existing
@nordhealth/components
to1.0.0
. - If using React, update
@nordhealth/react
to1.0.0
. - Install the latest
@nordhealth/css
package.
Here’s an example package.json
:
{
"dependencies": {
"@nordhealth/components": "^1.0.0",
"@nordhealth/css": "^1.0.4"
}
}
Localizing the components
Nord now provides a lightweight solution for localizing its components. Not all components need localizing, as for the most part snippets of text are set per instance. For example, the label on an Input will likely be changed every time you use it. Those cases are an app-level concern.
However, some components have text which has no reason to change per instance. For example, the usage instructions in the footer of the Command menu, or the accessible labels for next/previous month buttons of the Calendar.
For the latter cases, we provide a new localization mechanism. It is not possible or feasible for Nord to anticipate every locale in which the components might be consumed, so we rely on individual teams and applications to translate and configure localization. To ensure Nord components work out of the box, we bundle translations for en-US
.
Removing unnecessary localization
We now utilize browser’s built-in localizations for Calendar and Date Picker in Nord so there’s no need to translate the month, day, and similar names anymore. If you were previously using code similar to this to translate the Date Picker:
datePicker.localization = {
buttonLabel: "Valitse päivämäärä",
selectedDateMessage: "Valittu päivämäärä on",
prevMonthLabel: "Edellinen kuukausi",
nextMonthLabel: "Seuraava kuukausi",
monthSelectLabel: "Kuukausi",
yearSelectLabel: "Vuosi",
closeLabel: "Sulje ikkuna",
calendarHeading: "Valitse päivämäärä",
dayNames: ["Sunnuntai", "Maanantai", "Tiistai", "Keskiviikko", "Torstai", "Perjantai", "Lauantai"],
monthNames: [
"Tammikuu",
"Helmikuu",
"Maaliskuu",
"Huhtikuu",
"Toukokuu",
"Kesäkuu",
"Heinäkuu",
"Elokuu",
"Syyskuu",
"Lokakuu",
"Marraskuu",
"Joulukuu",
],
monthNamesShort: [
"Tammi",
"Helmi",
"Maalis",
"Huhti",
"Touko",
"Kesä",
"Heinä",
"Elo",
"Syys",
"Loka",
"Marras",
"Joulu",
],
locale: "fi-FI",
}
You can now remove it and follow our localization guidelines instead to create the necessary translations for Calendar and Date Picker:
export default {
$lang: "fi",
$name: "Suomi",
$dir: "ltr",
"nord-calendar": {
prevMonthLabel: "Edellinen kuukausi",
nextMonthLabel: "Seuraava kuukausi",
monthSelectLabel: "Kuukausi",
yearSelectLabel: "Vuosi",
},
"nord-date-picker": {
modalHeading: "Valitse päivämäärä",
closeLabel: "Sulje ikkuna",
buttonLabel: "Valitse päivämäärä",
selectedDateMessage: "Valittu päivämäärä on",
},
}
Defining types for event handlers
If you’re using our React components, the types for event handlers no longer need to be defined like this:
// TS complained unless you had a union of both types
function handleChange(e: FormEvent | Event) {}
<Input onChange={handleChange} />
In the latest 1.0.0
version, you can define them as:
function handleChange(e: Event) {}
<Input onChange={handleChange} />
Using new named slots
Our team has worked on unifying the naming of properties, slots, and similar in the system and some of these changes are not backwards compatible. If you were previously using the action
slot in Header component, it has now been renamed to end
to match the naming conventions we use elsewhere. So if you previously had this:
<nord-header>
<nord-button slot="action">Export</nord-button>
</nord-header>
You should now rename the action
slot to end
instead:
<nord-header>
<nord-button slot="end">Export</nord-button>
</nord-header>
Similarly, any slots that were previously called before
and after
, are now renamed to start
and end
in each component.
Stack component wrapping
We’ve improved the Stack component in the latest release, and with this, comes one breaking change. Previously, Stack would automatically allow its items to flow into multiple lines, but we’ve changed this to be opt-in instead to give a finer level of control to our users.
If you previously had this and wanted the items to wrap automatically depending on the viewport size:
<nord-stack>
<div></div>
<div></div>
</nord-stack>
You need to now explicitly use a property called wrap
to enable the same behaviour:
<nord-stack wrap>
<div></div>
<div></div>
</nord-stack>
Getting support
Have a question about migration? Please head over to the Support page for more guidelines and ways to contact us.