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 using Nunito Sans as main font. */
@import "~@dnvgl-onefoundation/onedesign/src/scss/main.scss";

/* On Premise for installation on customer servers using Nunito Sans as main font. */
@import "~@dnvgl-onefoundation/onedesign/src/scss/mainOnPrem.scss";

/* Version for apps hosted on DNV servers using Avenir Next as main font. */
@import "~@dnvgl-onefoundation/onedesign/src/scss/mainWeb.scss";

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.