NPM Setup

Required items before installation

Node.js - JavaScript runtime for building and running the project. Use winget install OpenJS.NodeJS to install it directly from the Windows store through the command line.
vsts-npm-auth - Microsoft tool to be able to authenticate on our Azure DevOps servers, to retrieve the packages from our npm feeds. Use npm install -g vsts-npm-auth to install via npmjs.

Add Custom Registry for Private Feed

We use our own Azure DevOps as a package repository for our private npm package feeds. To install these packages you need to configure your .npmrc file, which manages npm settings. The dnvgl and fortawesome registries, or URL feeds, needs to be added to this config file. The default npmjs registry will be included as an upstream source.

In your project root, create an empty file called .npmrc, and add the following registries to it:

@fortawesome:registry=https://pkgs.dev.azure.com/dnvgl-one/_packaging/dnvgl/npm/registry/
@dnvgl-onefoundation:registry=https://pkgs.dev.azure.com/dnvgl-one/_packaging/dnvgl/npm/registry/
always-auth=true

Generate Authentication Token

The previous section went through how to make your local .npmrc file. An authentication token needs to be added to your global .npmrc file which is already located at C:\Users\$USER\.npmrc.

Make sure you are in the project root and run the following command in a terminal after changing $USER to your actual desktop username:

vsts-npm-auth -Config .npmrc -TargetConfig C:\Users\$USER\.npmrc

Info. This doesn't need to be done for every project, and you'll only need to create a new npmrc file if you want to start a different project, and the token will remain valid for all of them.

Issues with obtaining an authentication token? Try the following fixes:

Ensure home drive is set to C: (More info at the bottom of this page: Centre of Enablement)
Use the absolute path for the local .npmrc file (-Config C:\path\to\project\.npmrc)
Use the -F flag (More info: Connect to Azure Artifacts)

More info about using internal packages in DNV can be found here.

Note: The generated token has a default validity of 3 months and might need to be generated again once it expires. you'll just need to run the command again when that happens.

Install OneDesign Styles

After the authentication token has been added successfully it is possible to install the OneDesign styles. The npm package contains both the compiled CSS and SASS source files.

npm install @dnvgl-onefoundation/onedesign@latest

The newest version of Fontawesome Pro (version 6) is a direct dependency and should have been installed when you ran the installation of OneDesign. If for some reason it hasn't installed, you can install it manually with the following command:

npm install @fortawesome/fontawesome-pro

Update dependencies to avoid security vulnerabilities

Some 3rd party dependencies might depend on other dependencies which can be out of date and exposed to security vulnerabilities.

After running npm install, check the report to see if any vulnerabilities are reported. You can run npm audit to scan for vulnerabilities, and npm audit fix to deal with non-breaking updates.

Import OneDesign Styles

To ensure that relative imports work correctly in your project, declare a root path Sass variable that points to the installed styles.

Add this line at the top of your main SCSS file:

$onedesign-root-path: "~@dnvgl-onefoundation/onedesign/src";

After that, import the base SCSS file that best aligns with your project requirements. The options are main.scss, mainOnPrem.scss, or mainWeb.scss.

Ensure that the root path variable is assigned before importing the base SCSS file by placing the variable assignment line above the base import line in your code.

/* Default styles. */
@import "~@dnvgl-onefoundation/onedesign/src/scss/config/npm/main.scss";

Note: Note that the path to the scss file has been updated from previous versions. Also, if you were using on-prem or web version of the import, please update to use the main version.

We no longer require a separate on-prem / web version, since we are now using Gantari as the default font and it doesn't have restrictions on usage anymore.

Loading Font fallbacks

By default, this package is distributed with Gantari as the main font, and no font-fallbacks are specified. You can, however, load separate fallbacks to suit your case, or additionally, create your own fallback.

Due to the size of the font files, we avoid setting the fallbacks by default to make sure we run a minimal needed overhead only.

These are the available font fallbacks to install:

Arabic

npm install @dnvgl-onefoundation/onedesign-fonts-ns-arabic

/* Import Noto Sans Arabic. */
@import "~@dnvgl-onefoundation/onedesign-fonts-ns-arabic/noto-sans-arabic.scss";

Cyrilic

npm install @dnvgl-onefoundation/onedesign-fonts-noto-sans

/* Import Noto Sans. */
@import "~@dnvgl-onefoundation/onedesign-fonts-noto-sans/noto-sans.scss";

Chinese (Simplified)

npm install @dnvgl-onefoundation/onedesign-fonts-ns-sc

/* Import Noto Sans. */
@import "~@dnvgl-onefoundation/onedesign-fonts-ns-sc/noto-sans-sc.scss";

Chinese (Traditional)

npm install @dnvgl-onefoundation/onedesign-fonts-ns-tc

/* Import Noto Sans. */
@import "~@dnvgl-onefoundation/onedesign-fonts-ns-tc/noto-sans-tc.scss";

Japanese

npm install @dnvgl-onefoundation/onedesign-fonts-ns-jp

/* Import Noto Sans. */
@import "~@dnvgl-onefoundation/onedesign-fonts-ns-jp/noto-sans-jp.scss";

Korean

npm install @dnvgl-onefoundation/onedesign-fonts-ns-kr

/* Import Noto Sans. */
@import "~@dnvgl-onefoundation/onedesign-fonts-ns-kr/noto-sans-kr.scss";

Thai

npm install @dnvgl-onefoundation/onedesign-fonts-ns-thai

/* Import Noto Sans. */
@import "~@dnvgl-onefoundation/onedesign-fonts-ns-thai/noto-sans-thai.scss";

This is how you can build your own fallback:

Import your necessary css from the list above and after importing all of them, add this css to your project (i.e, for a fallback to cover both Cyrilic characters and Thai):

:root {
  --font: "Gantari", "Noto Sans", "Noto Sans Thai", Arial, sans-serif;
  --font-base: "Gantari", "Noto Sans", "Noto Sans Thai", Arial, sans-serif;
  --font-regular: "Gantari Regular", "Noto Sans Regular", "Noto Sans Thai Regular", Arial, sans-serif;
  --font-italic: "Gantari Italic", "Noto San Italic", "Noto Sans Thai Italic", Arial, sans-serif;
  --font-semibold: "Gantari SemiBold", "Noto Sans SemiBold", "Noto Sans Thai SemiBold", Arial, sans-serif;
  --font-semibold-italic: "Gantari SemiBold Italic", "Noto Sans SemiBold Italic", "Noto Sans Thai SemiBold Italic", Arial, sans-serif;
  --font-extrabold: "Gantari ExtraBold", "Noto Sans ExtraBold", "Noto Sans Thai ExtraBold", Arial, sans-serif;
  --font-extrabold-italic: "Gantari ExtraBold Italic", "Noto Sans ExtraBold Italic", "Noto Sans Thai ExtraBold Italic", Arial, sans-serif;
}

Build

To be able to authenticate on a Build Pipeline, you need to add a task to your Azure Pipeline to include npm authentication for your .npmrc file.

More information is available here.