Configuring Environments

Common#

All versions of Hub require the following setup.

React and Hub V1

For most of Hub v1, using @iqmetrix/hub.common.tooling@2.x.x (check it in your package.json file), you need to follow the common environment configuration.

Node.js and NVM#

Different versions of the Hub framework require different versions of Node. NVM is a tool that will allow multiple versions of Node to be available on the same environment.

Using only Node.js

If you are not planning to support a Hub V2 application or an old Hub V1 application using hub.common.tooling@1.x.x, you do not need to install NVM. You can install the last version of Node.JS.

  1. Install NVM

  2. Verify your setup by installing a version of Node and checking its version.

    On Windows

    nvm install latest
    nvm use 12.14.1 # Use the version installed by the previous command

    On Mac

    nvm install node

    Checking versions

    node -v
    npm -v

    Hub aims to support as many recent versions of Node.js as possible. The specific version used is left to the discretion of the app owners.

  3. Optional - Some repositories use yarn as a package manager. You can install it with your current version of Node.

    npm install -g yarn

Azure DevOps authentication#

This authentications is necessary to be able to use @iqmetrix packages from Azure Artifacts. Authenticate with the iQmetrix NPM registry by following the instructions provided by Microsoft.

Authentication with Azure DevOps

Now iQmetrix is using Duo as 2FA, and for this reason, the token refresh using vsts-npm-auth package is no longer possible. Please, use the Linux/Mac configuration provided by Microsoft even if you are using a Windows Machine.

Your home directory's .npmrc file should include the following:

.npmrc
@iqmetrix:registry=https://pkgs.dev.azure.com/iqmetrix/_packaging/iqmetrix/npm/registry/
always-auth=true
; begin auth token
//pkgs.dev.azure.com/iqmetrix/_packaging/iqmetrix/npm/registry/:username=iqmetrix
//pkgs.dev.azure.com/iqmetrix/_packaging/iqmetrix/npm/registry/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]
//pkgs.dev.azure.com/iqmetrix/_packaging/iqmetrix/npm/registry/:email=npm requires email to be set but doesn't use the value
//pkgs.dev.azure.com/iqmetrix/_packaging/iqmetrix/npm/:username=iqmetrix
//pkgs.dev.azure.com/iqmetrix/_packaging/iqmetrix/npm/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]
//pkgs.dev.azure.com/iqmetrix/_packaging/iqmetrix/npm/:email=npm requires email to be set but doesn't use the value
; end auth token

The token set here is used locally on your computer. It is different for each user. Do not include this information in your application's repository.

The .npmrc file#

When creating a new Hub React App or Updating hub.coomon.tooling for Hub v1, you will need to create an .npmrc file in the application root to use iQmetrix's Azure Artifacts package registry (@iqmetrix/packageName).

You can skip this step if you are using the iQmetrix CRA Template to create a React app. This file already exists in the template.

.npmrc
@iqmetrix:registry=https://pkgs.dev.azure.com/iqmetrix/_packaging/iqmetrix/npm/registry/
always-auth=true
404/401 Errors

If you are getting an npm ERR! 404 or ERR! 401 Unauthorized when running npm install you may need still to setup ~/.npmrc with your Azure credentials as described in the previous section.

GitHub#

  1. Install git

  2. Optional - Install a git GUI

  3. Connect to GitHub with SSH

    Setup for SSH Keys

    Make sure you leave the password blank or you will have issues running NPM through other tools.

  4. Verify your installation is working by cloning a repository

    git clone git@github.com:iQmetrix/iQ.design.system.docs.git

Specific Hub Versions#

Each version of Hub requires different environment configuration.

React#

You can either run npm start in an existing app or create a new one to test your environment. No additional configuration should be necessary if you are using node 10+. To test, navigate to http://localhost:9000/#dev and confirm the app is running.

Hub v1#

These steps are for those using hub.common.tooling@2.x

If you are still using hub.common.tooling@1.x, upgrade it following the upgrading guide. To run non-upgraded Hub v1 applications, configure the old environment .

You can either run npm start in an existing app or clone the Hub.Boilerplate to test your environment. No additional configuration should be necessary if you are using Node 8+. To test, navigate to http://localhost:9000/#dev and confirm the app is running

If you have a problem or errors, check the Troubleshooting section from v1 HubBoilerplate.

Hub v2#

  1. Install and use Node.js 6.3.1

    nvm install 6.3.1
    nvm use 6.3.1

  2. Install node-gyp

  3. Clone the monorepo and navigate to the project source

    git clone git@github.com:iQmetrix/hub.git
    cd hub

  4. Install the CLI

    npm install -g hub.tools --registry https://pkgs.dev.azure.com/iqmetrix/_packaging/iqmetrix/npm/registry/

  5. Run the package.json setup script. This is only needed the first time you set up a clone of Hub v2.

    npm run setup

  6. Verify your setup by running hub.app.home

    cd projects/apps/hub.app.home
    hub serve

  7. Navigate to http://localhost:9000 and confirm the app is running

Edit this page
Last updated on by jfavelleIqMetrix