# 3.5.0 - 4.0.0 Nebular Migration
## Migration Purposes
Nebular 4.0 is a significant improvement and rework of the previous versions. We believe these changes bring Nebular to the new level of quality and feature-richness with:
- Updated look&feel with Eva Design System;
- New convenient and flexible Theming system;
- Custom CSS properties support in theming;
- Unified component interfaces (`@Input`'s and `@Output`'s);
- New Dark theme;
- Support of SVG Eva Icons.
To achieve all of this and allow Nebular to grow faster and better, we had to refactor a lot of internal implementations, as well as *public APIs*.
We hope that next Nebular versions won't receive such significant upgrades and the amount of breaking changes will be kept as low as possible.
## Nebular 3 LTS
Starting with Nebular 3 we introduce support policy schedule.
All major versions will receive 6 months of long-time support (LTS):
- critical bug fixes
- security fixes
- Angular major version update
This means that Nebular 3 will be maintained for the next 6 months until Angular 9 release.
We anticipate 3.6.0 version supporting Angular 8 in the following weeks.
## Migration Steps
The following migration steps are required to update:
- Update Angular to version 8 *required*
- Update Nebular to version 4 *required*
- Fix imports and component properties *required*
- Migrate Theme *depends*
- Migrate to `eva-icons` *optional*
###### 1. Update Angular to version 8
Nebular 4.0 is based on Angular version 8, thus the very first step is to update the last.
Since Angular has an automatic migration `ng update` in place, the update will look as follows:
```sh
ng update @angular/cli @angular/core
```
Most of the changes will be done automatically.
If you have any issues or your setup is more complex - refer to the https://update.angular.io/, select your Angular version and follow the steps
###### 2. Update Nebular to version 4
```sh
ng update @nebular/theme
```
Additionally, if you use any other Nebular packages, you can add them like this:
```sh
ng update @nebular/theme @nebular/auth @nebular/security
```
Since Nebular requires `@angular/cdk`, update it to the latest version:
```sh
ng update @angular/cdk
```
###### 3. Fix imports and component properties
Nebular 4.0 unifies a lot of component properties making them more intuitive and easier to use.
Complete table of changes could be found under [Properties changed in Nebular 4.0.0](https://github.com/akveo/nebular/tree/master/src/framework/theme/350-400-properties-changes.md) doc.
###### 4. Migrate Theme
This step depends on your setup.
In case when you use a CSS version of styles from `prebuilt/THEME_NAME.css` - no action is required, you can omit this step and move on to the next one.
If you use Nebular Theming or have custom themes, follow the steps below:
**Replace `/deep/` with `::ng-deep`**
So that it won't error with `dart-sass`, which is now the default Angular sass processor.
**Remove, replace, or temporary comment out removed sass mixins**
`nb-radial-gradient`, `nb-right-gradient`, `nb-hero-STATUS-gradient`. Comment out color sass functions (`tint`, `mix`, `darken`, `lighten`, etc).
We do this to stop sass throwing errors for being unable to process `undefined` values returned by `nb-theme` for removed and renamed variables.
At this point, your app should build but won't look good. Let's work on that.
**Update theme variables**
We suggest the following strategy on migrating to the new theme.
1) Comment out all of the variables changed inside of `nb-register-theme()` call
2) In case you changed global background/border colors, you need to update `color-basic` shades. Default shade for both `light` and `dark` variables looks like this:
```scss
color-basic-100: #ffffff,
color-basic-200: #f7f8fa,
color-basic-300: #edf0f4,
color-basic-400: #dde1eb,
color-basic-500: #c8cedb,
color-basic-600: #a7b0c1,
color-basic-700: #657084,
color-basic-800: #2e384f,
color-basic-900: #232a40,
color-basic-1000: #1a1f33,
color-basic-1100: #131729,
```
Where 100 - is the lightens color and 1100 - the darkest.
For the default theme, the following values will be used for backgrounds, borders, and texts colors:
```scss
background-basic-color-1: color-basic-100,
background-basic-color-2: color-basic-200,
background-basic-color-3: color-basic-300,
background-basic-color-4: color-basic-400,
border-basic-color-1: color-basic-100,
border-basic-color-2: color-basic-200,
border-basic-color-3: color-basic-300,
border-basic-color-4: color-basic-400,
border-basic-color-5: color-basic-500,
text-basic-color: color-basic-1000,
text-alternate-color: color-basic-100,
text-control-color: color-basic-100,
text-disabled-color: color-basic-500,
text-hint-color: color-basic-700,
```
This means that if you need to change the background color, copy the `color-basic` shades and update to with your custom color to reflect your color shades, starting with the whitish and finishing with the darkest shade.
Next - tune the `background-basic-color-N`, `border-basic-color-N` and `text-STYLE-color` variables, if you want the theme to take darker/lighter or simply different colors.
3) In case you changed status colors (primary, success, warning, etc), you would need to update those too. For example, current primary color shades look like this:
```scss
color-primary-100: #f2f6ff,
color-primary-200: #d9e4ff,
color-primary-300: #a6c1ff,
color-primary-400: #598bff,
color-primary-500: #3366ff,
color-primary-600: #274bdb,
color-primary-700: #1a34b8,
color-primary-800: #102694,
color-primary-900: #091c7a,
```
Where 100 - is the lightest blue color, 500 is the one used for buttons, checkboxes, etc, and 900 - the darkest.
Copy the shades and update it with the color of your choice.
[Eva Colors](https://colors.eva.design) is a great tool to generate colors pallet from a given brand color.
Next - you can tune colors used for element states:
```scss
color-primary-focus: color-primary-700,
color-primary-hover: color-primary-400,
color-primary-default: color-primary-500,
color-primary-active: color-primary-600,
color-primary-disabled: color-primary-300,
```
You can adjust these settings for each of the colors, to make states use lighter or darker colors.
At this stage you can already check the result - background and color should look similar to the previous version.
4) Adjust the rest of the theme variables
More details on the changes you can check in the [Theme variables change in Nebular 4.0.0](https://github.com/akveo/nebular/tree/master/src/framework/theme/350-400-theme-variables-changes.md) doc.
For those variables that are removed, you can create custom local variables under your theme.
5) Fix changes to particular element variables.
Starting with Nebular 4.0 we will be moving to restrict direct modification of component variables through theme interface, making those private internal implementations.
We believe that flexibility provided by the themes variables will allow achieving smaller and better changes of the look&feel without modifying specific component theme variables.
But in a case when you modified component theme variables, e.g. `card-bg`, `header-fg`, and need those changes, make the change in accordance with the
[Components variables changes in Nebular 4.0.0](https://github.com/akveo/nebular/tree/master/src/framework/theme/350-400-component-variables-changes.md) doc.
6) Fix all `nb-theme(NON-EXISTING-VAR)` calls.
In case you used `nb-theme` calls in your scss files directly accessing theme or component variables, you would need to fix those calls to reference new theme variables.
You can follow both [Theme variables change in Nebular 4.0.0](https://github.com/akveo/nebular/tree/master/src/framework/theme/350-400-theme-variables-changes.md) and
[Components variables changes in Nebular 4.0.0](https://github.com/akveo/nebular/tree/master/src/framework/theme/350-400-component-variables-changes.md) docs to make a better decision on what should be changed to what.
At the end - check your console output - it should not contain any sass warning.
**Enable sass mixins and color functions**
Since Nebular 4.0 has a complete color palette for each of the color, we believe that usage of sass color function could be drastically decreased.
Moreover, if you are looking to [enabling Nebular custom css properties mode](https://akveo.github.io/nebular/docs/design-system/enable-css-properties-mode#enable-css-custom-properties-mode),
calculation against colors and sizes should not be done at the build time (using sass), but rather at the run-time in the browser (utilizing css `cacl()`) function.
If you are looking to migrate your project to css custom properties, please refer to this [issue](https://github.com/akveo/nebular/issues/1523).
**Check everything and let us know**
We hope that the process won't be too complicated, though it may require some additional steps we couldn't presume. If that's the case - please post your question to this [issue](https://github.com/akveo/nebular/issues/1524).
###### 5. Migrate to `eva-icons`
Nebular 4.0 introduces new `nb-icon` component and `NbIconLibraries` service to host SVG and Font icon packs.
As a breaking change, Nebular moves from `nebular-icons` package to much more popular [Eva Icons pack](https://akveo.github.io/eva-icons/) consisting of 480+ beautiful SVG icons.
We believe this will bring more quality and variety to interfaces based on Nebular.
Now all Nebular components internally use `` component utilizing Eva Icons SVG icons. More details on [nb-icon](https://akveo.github.io/nebular/docs/components/icon) component.
There are two ways to upgrade:
**Migrate to Eva Icons** (recommended):
1) install Eva Icons Nebular package
```sh
npm i @nebular/eva-icons
```
2) register `NbEvaIconsModule` in the `app.module.ts`
```ts
import { NbEvaIconsModule } from '@nebular/eva-icons';
@NgModule({
imports: [
// ...
NbEvaIconsModule,
],
})
```
3) Search for all usages of ``. Complete icons list https://akveo.github.io/eva-icons/.
4) Search for `icon: 'nb-*'` references in properties for such components as Menu, Actions, Tabs, etc. Replace those with `icon: 'icon-name'`. Please note, there is no need to specify any icon prefix (such as `eva-` or `nb-`) since the prefix is specified when the icon package is registered in Nebular.
4) Update styles if necessary.
5) if you have `nebular-icons` installed, remove the package and all references.
**Continue using nebular-icons**
This option is also possible, but please note, Nebular Component will still use Eva Icons pack for internal component icons, such as `close`, `arrow-down`, `arrow-up`, etc.
1) Register nebular-icons as a pack for Nebular in your `app.component.ts`
```ts
import { NbIconLibraries } from '@nebular/theme';
constructor(private iconLibraries: NbIconLibraries) {
this.iconLibraries.registerFontPack('nebular', { iconClassPrefix: 'nb' });
this.iconLibraries.setDefaultPack('nebular');
}
```
3) Search for all usages of `` without the `nb-` prefix since prefix is specified when the icon package is registered in Nebular.
4) Search for `icon: 'nb-*'` references in properties for such components as Menu, Actions, Tabs, etc. Replace those with `icon: 'icon-name'` without `nb-` prefix since it is unnecessary and covered under the hood.