Migration guide

From 0.x to 1.0

There are fundamental breaking changes from ui-* 0.* to 1.0. This guide aims at making your transition smooother. It is also meant for developers who will maintain the project.

Repos

The first big change is that we no longer have multiple repos, like ui-react-components, ui-css-components, ui-illustrations and so on. Now all basic components live in the ui repo, making maintenance and consumption easier. It is still possible to consume only the CSS 'though. To know more about the reasoning behind this change, take a look at ui-react-components/issues/49.

Paths

It was decided to keep components in the root of the project. This way we accomplish very simple and mnemonic paths, such as import * as Button from @klarna/ui/Button`. Some special components may be under a namespace, like uncontrolled, but the most common ones will follow this rule. Also, keeping the components there avoids having an additional build or publish step to move things, something that makes reasoning about where things are more difficult.

CSS Classes

The cui__ prefix was dropped. So classes now are as simple as dialog, dialog__overlay, etc. If you have overriden something in your project, instead of renaming it, consider using another class and/or custom styles (TBD).

Export standards

It was agreed all components with subcomponents should export all, with the main component being called Main. For instance, you should import and use the ContextMenu as follows:

import * as ContextMenu from '@klarna/ui/ContextMenu'

...
  <ContextMenu.Main>
    <ContextMenu.Item>Menu title</ContextMenu.Item>
    <ContextMenu.Link href="#link">Menu link</ContextMenu.Link>
    ...
  </ContextMenu.Main>

This way you can choose to import only the components you need (import { Main, Item, Link } from '@klarna/ui/ContextMenu' and it will work with webpack's tree shaking. Read more about this change at ui-react-components/issues/50.

Designs

In previous versions components came with design as a prop. So if you wanted to have a blue button, you would do <Button design="primary" />, while now each design is its own component, as in <Button.Primary />.

Unit tests

Unit tests are going to be skipped and replaced by simply a) making sure the showcase shows all variations of components and b) running a simpler check that makes sure this variations doesn't break.

Tips

If you have tons of replaces to do, you can always use the grep+sed. Here's the syntax for MacOS:

grep -lr 'ui-react-components/components' PATH_TO_SRC/**/*.jsx | \
xargs -I@ sed -i '' 's/ui-react-components\/components/ui/' @