Installation

ZUi web is bundled as npm package and hosted in ZEISS Azure DevOps repository. To get access to our Azure DevOps project, please join our MS-Teams channel "tech support" and request access. We will add you to our DevOps project as an observer so that you can use the packages and see our issue tracker.

All ZUi packages are scoped with @zeiss/*. You have to make sure that npm (or yarn, pnpm) can access this registry. For this you have to create a .npmrc file in your project root directory.

@zeiss:registry=<URL TO REPOSITORY>
always-auth=true

There are two options for which value to use for <URL TO REPOSITORY>:

(Recommended) Use the NPM registry of your own Azure DevOps project and configure ZUi Web as an upstream source (see below "Configure Azure DevOps NPM upstream source"). This way you don't need to have access to the ZUi Web project itself and your build pipeline can use the ZUi packages too.
(Not recommended) Use the ZUi Web registry directly. The URL is https://pkgs.dev.azure.com/ZEISSgroup/DI_ZUi-Web/_packaging/DI_ZUi-Web%40Production/npm/registry/. This is not recommended because you need to have access rights to the ZUi Web project first and it won't work in your Azure DevOps build pipeline. This is only recommended for testing ZUi when you don't have an Azure DevOps project (yet).

If you need further details, you can visit the Azure DevOps Documentation.

Authenticate NPM registry

Windows

Then, run vsts-npm-auth in your project root directory to get an Azure Artifacts token automatically added to your user-level .npmrc file. It is important that you don't save the credentials in your project, because this file will be checked in.

vsts-npm-auth -config .npmrc

N.B. The most recent versions, changed the params, if you get any error, try:

vsts-npm-auth -C .npmrc

instead.

Note: You don't need to do this every time. npm will give you a 401 Unauthorized error when you need to run it again.
To refresh an expired token, you probably have to delete the old user-level .npmrc file before re-running the command will work without errors.

To install this tool on Windows run:

npm install -g vsts-npm-auth --registry https://registry.npmjs.com --always-auth false

Other Operating Systems

Setup credentials

Step 1

Copy the code below to your user .npmrc.

; begin auth token
//pkgs.dev.azure.com/ZEISSgroup/DI_ZUi-Web/_packaging/DI_ZUi-Web%40Production/npm/registry/:username=ZEISSgroup
//pkgs.dev.azure.com/ZEISSgroup/DI_ZUi-Web/_packaging/DI_ZUi-Web%40Production/npm/registry/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]
//pkgs.dev.azure.com/ZEISSgroup/DI_ZUi-Web/_packaging/DI_ZUi-Web%40Production/npm/registry/:email=npm requires email to be set but doesn't use the value
//pkgs.dev.azure.com/ZEISSgroup/DI_ZUi-Web/_packaging/DI_ZUi-Web%40Production/npm/:username=ZEISSgroup
//pkgs.dev.azure.com/ZEISSgroup/DI_ZUi-Web/_packaging/DI_ZUi-Web%40Production/npm/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]
//pkgs.dev.azure.com/ZEISSgroup/DI_ZUi-Web/_packaging/DI_ZUi-Web%40Production/npm/:email=npm requires email to be set but doesn't use the value
; end auth token

Step 2

Generate a personal access token with Packaging read & write scopes.

If you reading this at our wiki space go to Artifacts -> @zeiss/zui, click the connect to feed button and go to npm. Choose the Other tab on the right side and you will see this page there. The difference is, that you now can click to "personal access token" above. Now you can create a new token with the rights you need.
Step 3

Base64 encode the personal access token from Step 2.

One safe and secure method of Base64 encoding a string is to:
1. From a command/shell prompt run:
```
node -e "require('readline').createInterface({input:process.stdin,output:process.stdout,historySize:0}) .question('PAT> ',p => { b64=Buffer.from(p.trim()).toString('base64');console.log(b64);process.exit(); })"
```
2. Paste your personal access token value and press Enter/Return
3. Copy the Base64 encoded value
Step 4

Replace both [BASE64_ENCODED_PERSONAL_ACCESS_TOKEN] values in your user .npmrc file with your Base64 encoded personal access token from Step 3.

Configure Azure DevOps NPM upstream source

Setting up an Azure DevOps NPM upstream source has several advantages over using the ZUi Web NPM repository directly:

Users don't need access rights to the ZUi Web project but only access rights to your own project.
Your build pipeline can use ZUi packages
If the URL to the ZUi Web registry might change in the future, you only need to update the upstream source without having to change .npmrc files in your repositories.

When using an upstream source, your local developer machine will first ask the registry of your own project for the ZUi packages. Your registry will then go to the ZUi Web registry to actually get the packages.

See Azure DevOps Documentation - Configure upstream source for a detailed description.

Use azure-feed://ZEISSgroup/DI_ZUi-Web/DI_ZUi-Web@Production as feed locator.

Install NPM Package

You can install the packages via npm:

npm i @zeiss/zui
npm i @zeiss/zui-icons

The actual setup depends on your application setup i.e. are you using a modern SPA framework that comes with a bundler or do you want to use ZUi web in a plain html page?

Setup with JavaScript applications

Somewhere in your application you have to include this code to setup ZUi:

import "@zeiss/zui"
import "@zeiss/zui-icons"
import { 
    registerTypefaces, 
} from "@zeiss/zui"

registerTypefaces("/fonts")

Let's take a look at these lines in more detail:

import "@zeiss/zui" is the most important part. This registers the ZUi web components and makes the tags for the components available in your application. import "@zeiss/zui-icons" is doing the same for the zui icons.

registerTypefaces("/fonts") is used to setup the fonts that are used by ZUi web components. See Fonts.

Setup without a bundler

The ZUi Web packages contain different types of bundles. To use ZUi Web without a bundler (for example in a plain HTML file), we provide ES modules. To use them, add the following code to your HTML file:

<script src="node_modules/@zeiss/zui/dist/index.browser.bundle.esm.js" type="module"></script>
    <script src="node_modules/@zeiss/zui-icons/dist/index.bundle.esm.js" type="module"></script>
    <script type="module">
        import { 
           registerTypefaces, 
        } from "/node_modules/@zeiss/zui/dist/index.esm.js"

        registerTypefaces("/fonts")
    </script>

Notice the paths in the import ... from <PATH> statements. Using node_modules works for local setup. You should adapt this path to a static hosted version of ZUi Web. For this you should upload the ZUi packages to a CDN or any other web server. Always point to the *.esm.js files. This enables modern browsers (see browser support) to load all needed javascript modules.

Themes and colors

To set a theme for the application, you have to the <zui-theme-provider> component:

// somewhere at the top of your component tree
<zui-theme-provider theme="zbds-light">
   ...
</zui-theme-provider>

For more information to themes an colors see Themes or Migrationguide.

TypeScript

ZUi web is implemented with TypeScript and we do provide typings in the @zeiss/zui package. You don't need any further setup.

The minimal required TypeScript version is 4.5.5

Maybe older versions do work as well but may need skipLibCheck: true in the tsconfig.json.