# ng-ui-scale-lib: Use Scale UI as a library in a custom project

## CI/CD configuration

CI/CD is running with gitlab pipelines.
The configuration is located in the file `.gitlab-ci.yml`.
The `gitlab-ci.yml` file contains two jobs:

1. `publish_library`: publishes the library in the npm registry.
   It runs the script `prepare-release.mts` from the `scripts` directory.
   The script updates the `ng-ui-scale` version, and updates the current `package.json` version, and then publishes the library.
   This job is supposed to be triggered by the `ng-ui-scale` pipeline when a new version is released.
2. `publish_custom_project`: publishes the custom project `ng-ui-scale-custom`.
   This job is supposed to be executed after `publish_library`. It triggers the `ng-ui-scale-custom` pipeline to publish the custom project.

### Points to improve

The processes for publishing the library and deploying custom projects need to be more robust.
Right now, if the custom project deployment fails after the library has been published,
we can't restart the whole process because the library publication will fail due to it already being published.
Similarly, if the custom project is already deployed, and we want to rerun the pipeline,
it will fail because the project is already deployed.
The only solution we currently have is to create another release candidate with a new version,
which is both pointless and time-consuming.

## Migration from `scale-ui-scripts` to vite-based project using the `ng-ui-scale-lib` library

This short walk-through shows how to migrate a tenant project based on `scale-ui-scripts` to a vite-based project using
the `ng-ui-scale-lib`.

### 1. Update the `package.json` file

in `devDependencies` section:

```diff
- "@deviceinsight/scale-ui-custom-scripts": "5.7.0",
- "@deviceinsight/scale-ui-types": "2.6.0",
+ "vite": "^4.4.5",
+ "@vitejs/plugin-react": "^4.0.4",
+ "vite-plugin-environment": "^1.1.3",
```

in `dependencies` section:

```diff
+ "@deviceinsight/ng-ui-scale-lib": "{latest_version}"
```

`@deviceinsight/scale-ui-custom-scripts` is not needed because `vite` takes over its responsibilities.

`@deviceinsight/scale-ui-types` is not needed because the library `ng-ui-scale-lib` provides the types.

Along with vite, two plugins are installed:

-   `@vitejs/plugin-react` required in every react-based project
-   `vite-plugin-environment` required to read the environment variables with prefix `REACT_APP`.

Then, install the new dependencies with command `npm install`.

### 2. Change the script field

```diff
-"start": "scale-ui-custom start",
-"build": "scale-ui-custom bundle",
+"start": "vite",
+"build": "vite build",
```

### 3. Create the vite configuration file `vite.config.js`

```js
import {defineConfig} from 'vite';
import react from '@vitejs/plugin-react';
import EnvironmentPlugin from 'vite-plugin-environment';

export default defineConfig({
	plugins: [react(), EnvironmentPlugin('all', {prefix: 'REACT_APP_', defineOn: 'import.meta.env'})]
});
```

### 4. Create the index.html file

```html
<!doctype html>
<html lang="en">
	<head>
		<meta charset="UTF-8" />
		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
		<title>ScaleUI Custom Project</title>
	</head>
	<body>
		<div class="di app-wrapper">
			<div id="app"></div>
		</div>
		<script type="module" src="/node_modules/@deviceinsight/ng-ui-scale-lib/dist/setupRuntimeEnv.js"></script>
		<script type="module" src="/src/index.tsx"></script>
	</body>
</html>
```

The file must contain the following elements in the body:

```html
<div class="di app-wrapper">
	<div id="app"></div>
</div>
<script type="module" src="/node_modules/@deviceinsight/ng-ui-scale-lib/dist/setupRuntimeEnv.js"></script>
```

The `div` elements are required for the correct display of the application. The `script` element is required to set up
the runtime environment.

The last element of the body:

```html
<script type="module" src="/src/index.tsx"></script>
```

Includes the entry point of the application.
The path to the file might be different in your application, it's just an
example.

### 5. Create the entry point file

The following snippet shows the simplest entry point file:

```tsx
import {StrictMode} from 'react';
import {createRoot} from 'react-dom/client';
import {BrowserRouter} from 'react-router-dom';

import {initializeApp, App} from '@deviceinsight/ng-ui-scale-lib';
import '@deviceinsight/ng-ui-scale-lib/dist/style.css';

async function setup() {
	await initializeApp();
	// await customizations(); <-- your customizations
}

setup().then(() =>
	createRoot(document.getElementById('app')!).render(
		<StrictMode>
			<BrowserRouter>
				<App />
			</BrowserRouter>
		</StrictMode>
	)
);
```

The file above does the following things:

1. Imports the styles of the `ng-ui-scale` application.
2. Initializes the application with the `initializeApp` function.
3. Executes the custom initial code. This step is optional.
4. Renders the application with the `createRoot` function.

Note that the `<App />` must be wrapped into `BrowserRouter` if you want to add custom pages to the
application. `<StrictMode>` is optional but recommended.

### 6. Fix the imports of the custom api functions

If your application used any custom api methods, they were imported from the already removed
package `@deviceinsight/scale-ui-types`. These methods are now provided by the `ng-ui-scale-lib` library, so the only
thing that must be change is the imports. All the methods are available in the
package `@deviceinsight/ng-ui-scale-lib/api`.

```diff
-import {RouteApi} from "@deviceinsight/scale-ui-types";
+import {RouteApi} from "@deviceinsight/ng-ui-scale-lib/api";
```

### 7. Upgrade TypeScript to version 5 and other dependencies to the latest version

If your project is still working on TypeScript version 4, you must upgrade it to version 5.
In the `tsconfig.json` set the `moduleResolution` to `bundler`:

```
{
  "compilerOptions": {
    "moduleResolution": "bundler"
    ...
  }
}
```

Upgrade also `@deviceinsight/ng-ui-components` and `@deviceinsight/ng-ui-basic-components` if they are used in your
project.

Then fix all the TypeScript errors that might occur.

### 8. Run your application

Now the migration is done and your application is ready. Run it with command `npm start`.
