CDC Data Hub React Web Components

Project Name: CDC Data Hub Analytics and Visualization Documentation
GitHub Link: cdh-dav
Point of contact: Nishant Nepal John Bowyer
Organizational unit: DDPHSS/IAD/ADB
Related projects: OPHDST/IAD/ADB/CDH
Related investments: Pending Public Release
Governance status: Pending Public Release
Program official: Sachin Agnihotri

Overview

The CDC Data Hub React Web Client Application performs the last mile (S component - Serving, Sharing and Storytelling) in the IDEAS Framework. The application is a React Single Page Application (SPA) that may be hosted in multiple envronment such as WCMS. Development of PowerApp React components is also under evaluation.

React Client Libraries - React / WCMS

Component	Tag	Description
@cdc/cdccore	n/a	This is an internal package that is consumed by external facing packages in CDC React Components. The cdccore component contains shared components, styles and assets.
@cdc/cdcheader	`<CDCHeader />`	`<CDCHeader />` is a React component produced by the CDC for displaying a standard page header.
@cdc/cdcmarkdown	`<CDCMarkdown />`	`<CDCMarkdown />` is a React component produced by the CDC for importing markdown data from a separate source link.
@cdc/cdcsidebar	`<CDCSidebar />`	`<CDCSidebar />` is a React component produced by the CDC that displays a sidebar menu.

@cdc/cdcsitetitle	`<CDCSiteTitle />`	`<CDCSiteTitle />` is a React component produced by the CDC that displays a site title menu with breadcrumbs.

Live Demo hosted in WCMS

Dev
Staging

Initial Setup to Use CDC React components

Install package from GitHub

GitHub has the latest instructions for installing packages from GitHub here:

GitHub Installation

Recipe in GitHub to Generate Personal Access Token

There's two ways to authenticate - use "token" for username and the token path for password, or use an .npmrc file.
- **npm login:*-From your root repo, commandline, run this command:
```
npm login --scope=cdcgov --registry=https://npm.pkg.github.com
```
It will ask for login info, and you'll use your token as the account password.
- **.npmrc file:*-Create an .npmrc file in your root with these contents (replace TOKEN with your token):
```
cd <your-repo-project dir>
npm set //npm.pkg.github.com/:_authToken $GITHUB_TOKEN
echo "@cdcgov:registry=https://npm.pkg.github.com/" > .npmrc
echo "//npm.pkg.github.com/:_authToken=$GITHUB_TOKEN" >> .npmrc
echo "always-auth=true" >> .npmrc
```
⚠️ **Important:*-Make sure .npmrc is in your .gitignore. It's your login credentials, shouldn't exist in your repo.
If you've done this successfully, you should be able to install this like any other npm library:
```
npm install cdcgov/cdh-lava-react
```

Requirements

-react v16+

There are 2 SVG assets included in CDCHeader. If you're using webpack, you'll need a rule in your webpack.config.js to treat them as assets.

  rules: [
    {
      test: /\.(png|jpe?g|gif|svg)$/i,
      type: 'asset/resource',
    }
    ...

Usage

Once you've installed this package in your local JS project via npm, you can include these modules in your main js file:

import { CDCHeader, CDCSiteTitle, CDCBody, CDCFooter } from '@cdcgov/cdh-lava-react';
// This includes the built CSS files
import '@cdcgov/cdh-lava-react/assets/css/bootstrap.min.css';
import '@cdcgov/cdh-lava-react/assets/css/app.min.css';

Themes

Template Package supports 11 themes. theme-blue is included in app.min.css by default. To use, add a class to your page body element:

<body class="theme-blue">

For the other themes, you'll need to include the associated theme css and use its associated theme-<color> class.

theme-amber.min.css
theme-brown.min.css
theme-cyan.min.css
theme-green.min.css
theme-indigo.min.css
theme-orange.min.css
theme-pink.min.css
theme-purple.min.css
theme-slate.min.css
theme-teal.min.css

More info on available colors here

Favicon

The default CDC favicon is available in assets/imgs/favicon.ico. Either pull it in ask with the SVGs in webpack config, or copy to your public folder and reference appropriately.

<link rel="icon" href="%PUBLIC_URL%/assets/imgs/favicon.ico" />

Icon font

Template Package includes a icon webfont file that adds a host of icons from FontAwesome 5 as well as created icons. The full list can be seen here.

CDC Icons

<span class="cdc-icon-globe_03"></span>

Bootstrap styles

Template Package is built on top of Bootstrap 4, so it includes all core Bootstrap styles and additional styles for our modules. Some more information on available styles:

Bootstrap Style

React Components

Currently the components are quite flat, just enough to render the same site header and footer used by the rest of CDC. If you have any questions about page structure or elements, or Template Package in general, send an email to wcms@cdc.gov.

CDCHeader

Accepts props:

-search: boolean [default true] enable / disable display of header search

  <CDCHeader search={ true }></CDCHeader>

CDCSiteTitle

Accepts props:

-title: The site title -tagline: A tagline under the site title

  <CDCSiteTitle
    title="Demo Site"
    tagline="Demo tagline"
  >
  </CDCSiteTitle>

CDCBody

Displays children inside a body wrapper.

  <CDCBody>
    <h2>Test</h2>
    <p>
      Site content
    </p>
    ...
  </CDCBody>

CDCFooter

Accepts no props.

  <CDCFooter></CDCFooter>

Set up Git

NOTE: Must Logout of ZScaler

Check version
```
git --version
```

If version is not >= v2.39.0, Install Git

sudo apt-get install git

or

sudo apt-get upgrade git

Modifying and Updating Components

Prequisites

Follow set up instructions for NodeJS and NPM:

Run from Ubuntu-20.04, use WSL if Windows
NodeJS and NPM Getting Started

Initial Setup to modify core components

This repository is a monorepo that is managed with Lerna and uses yarn for package management. Make sure you have yarn installed before beginning. To work on individual packages you must setup the entire monorepo.

Clean up existing caches

sudo yarn cache clean
sudo npm cache clean --force
sudo lerna clean
nx cache clear --all
find . -name "node_modules" -type d -prune -exec sudo rm -rf '{}' +

Setup Yarn

NOTE: MUST LOGOUT: Sign out of ZScaler and run the following

cd $HOME
npm --version
sudo npm install -g yarn
yarn --version
cd cdc-react
sudo yarn install

Make the yarn cache available to all users

sudo chmod -R 777 /home/[your_alias]/.cache/yarn

example

sudo chmod -R 777 /home/zfi4/.cache/yarn

or

sudo chmod -R 777 /usr/local/share/.cache/yarn/v6

Setup Lerna

Install Lerna and initialize all the packages for you. NOTE: MUST LOGOUT: Sign out of ZScaler and run the following

cd cdc-react
sudo yarn global add lerna
sudo yarn install
sudo lerna init
sudo lerna bootstrap

Setup Vite

NOTE: MUST LOGOUT: Sign out of ZScaler and run the following

Install Vite globally using Yarn:
```
cd cdc-react
sudo yarn global add vite
```
Check if Vite is added to your PATH environment variable. You can check this by running the following command:
```
echo $PATH
```
If you do not see the path to the directory where Vite is installed (e.g., /usr/local/bin), you need to add it to your PATH. You can do this by adding the following line to your shell profile file :
```
cd $HOME
nano .bashrc
```
Add the following line to the end of the file:
```
export PATH="$PATH:/usr/local/bin"
```
Run the following command to reload the profile file:
```
source .bashrc
```

Setup Sass

Run the following command to install Sass globally.

sudo yarn global add sass

Setup Vitest

Run the following command to install Sass globally.

sudo yarn global add vitest
sudo yarn global add @vitest/ui
sudo yarn global add jsdom
sudo yarn install

Set up .env Environment Variables

Install dotenv. NOTE: MUST LOGOUT: Sign out of ZScaler and run the following
```
sudo yarn add dotenv  -W
```
Create a .env file in the root of your project using the following command:
```
touch .env
```
Set the following environment variables to tell your index.html which server to point to for the Analytics collection:
```
cd cdc-react
nano .env
```
Add the following lines to the file:
```
REACT_APP_CDC_PATH=https://www.cdc.gov
```
create an .env.development.local file
```
touch .env.development.local
```
Set the following environment variables to tell your index.html which server to point to for the Analytics collection:
```
cd cdc-react
nano env.development.local
```
Add the variable

REACT_APP_CDC_PATH=https://wwwdev.cdc.gov

Setup Adobe Analytics

-copy the following into the bottom of the of your index.html page:

<!-- Begin Adobe Analytics code version: JS-2.0 -->
<script src="%REACT_APP_CDC_PATH%/JScript/metrics/topic_levels.js"></script>
<script src="%REACT_APP_CDC_PATH%/JScript/metrics/adobe/analytics_cdcgov.js"></script>
<noscript>
  <a href="https://cdc.112.2o7.net">
    <img
      src="https://cdc.112.2o7.net/b/ss/cdcgov/1/H.21--NS/01/H.21--NS/0"
      height="1"
      width="1"
      alt="Web Analytics"
    />
  </a>
</noscript>
<!--/DO NOT REMOVE/-->
<!-- End Adobe Analytics code version: JS-2.0 -->

Set the following environment variables to tell your index.html which server to point to for the Analytics collection:

IMPORTANT wwwdev.cdc.gov reports to the "test" Adobe Analytics suite, and is accessible to everyone from the intranet. .env is used at build time so you may need to set up some external proxy server like NGINX. There are many ways to do this that are out of scope, however make sure this is figured out before dev deployment.

If you are using NGINX make a proxy route to /JScript which will point that path to www.cdc.gov and then set the REACT_APP_CDC_PATH= to nothing in the .env file. This will remove the path at build time and let nginx handle the rest.

Build All Components

Run the following command to build all of the packages in the correct order.

cd cdc-react
sudo lerna run build --stream --verbose

Build Individual Components

To begin working on an individual package, run the following, replacing package_name with the package's name (ex: @cdc/map).

cd cdc-react
sudo lerna run --scope @cdc/package_name start

Run Individual Components - cdccore

cd cdc-react
sudo lerna run  --scope @cdc/cdccore start  --verbose

Run Individual Component - cdcmarkdown

cd cdc-react
sudo lerna run  --scope @cdc/cdcmarkdown start  --verbose

Run Individual Component - cdcsitetitle

cd cdc-react
sudo npx lerna run  --scope @cdc/cdcsitetitle start  --verbose

Run Individual Component - cdcheader

cd cdc-react
sudo npm run  --scope @cdc/cdcheader start  --verbose

Run Individual Component - cdcsidebar

cd cdc-react
sudo npm run  --scope @cdc/cdcsidebar start  --verbose

TemplatePackage-React

This package includes assets and components needed to recreate the CDC site header, site title, and footer.

Set up GitHub Security: Option 1: Credential Manager: On Windows

GCM is included with Git for Windows. During installation you will be asked to select a credential helper, with GCM listed as the default.

Set up GitHub Security: Option 1: Credential Manager: On Ubuntu: Primary

Reference: Microsoft Learn Reference: GitHub Reference: GitHub Env NOTE: Must Logout of ZScaler

cd $HOME

NOTE: LOG OUT OF ZSCALER

Download

wget "https://github.com/GitCredentialManager/git-credential-manager/releases/download/v2.0.886/gcm-linux_amd64.2.0.886.deb" -O /tmp/gcmcore.deb

Once the script is downloaded, make it executable by running:
```
sudo dpkg -i /tmp/gcmcore.deb
```
This will install Git Credential Manager Core on your Ubuntu system.
```
git-credential-manager configure
```

Update .bashrc to set the credential type to cache

cd $HOME
nano ~/.bashrc
export GCM_CREDENTIAL_STORE=cache
export GCM_PROVIDER=github
source ~/.bashrc

or use git config

git config --global credential.credentialStore cache

Set Helper
```
git-credential-manager configure
```

Save User Name

git config --global user.name "John Bowyer"
git config --global user.email  "jcbowyer@hotmail.com"
git credential-manager store

If everything is installed correctly, this command will output the version number of Git Credential Manager Core.

Set up GitHub Security: Option 2 SSH

Check for existing SSH keys

Open Terminal.

Enter ls -al ~/.ssh to see if existing SSH keys are present.

$ ls -al ~/.ssh
# Lists the files in your .ssh directory, if they exist

Check the directory listing to see if you already have a public SSH key. By default, the filenames of supported public keys for GitHub are one of the following.
- id_dsa.pub
- id_ecdsa.pub
- id_ed25519.pub
Either generate a new SSH key or upload an existing key.
- If you don't have a supported public and private key pair, or don't wish to use any that are available, generate a new SSH key.
- If you see an existing public and private key pair listed (for example, id_rsa.pub and id_rsa) that you would like to use to connect to GitHub, you can add the key to the ssh-agent.

Generate SSH keys if missing

Open Terminal
Paste the text below, substituting in your GitHub email addres
```
ssh-keygen -t ed25519 -C "your_email@example.com"
```
Log in to your GitHub account and navigate to your account settings.
Click on "SSH and GPG keys" in the left sidebar.
Find the incorrect key in the list of SSH keys and click "Delete".
Click on "New SSH key" and give the key a title.
Paste your new public key into the "Key" field and click "Add SSH key".

Add Your Key to GitHub

Open Terminal.
nano ~/.ssh/id_ed25519.pub
Copy the SSH public key to your clipboard.
In the upper-right corner of any page, click your profile photo, then click Settings.
In the upper-right corner of any page, click your profile photo, then click Settings.
Click New SSH key or Add SSH key.
In the "Title" field, add a descriptive label for the new key. For example, if you're using a personal laptop, you might call this key "Personal laptop".
Select the type of key, either authentication or signing. For more information about commit signing, see "About commit signature verification."
Paste your public key into the "Key" field.
Click Add SSH key.
Authorize the key

How to Publish an NPM Package to GitHub Packages on Windows

This guide outlines the steps to publish an NPM package to GitHub Packages from a Windows environment.

1. Set `NODE_AUTH_TOKEN` Environment Variable

Set the NODE_AUTH_TOKEN environment variable with your GitHub token:

Using Command Prompt: setx NODE_AUTH_TOKEN "Your_GitHub_Token"
Using PowerShell: [System.Environment]::SetEnvironmentVariable('NODE_AUTH_TOKEN', 'Your_GitHub_Token', [System.EnvironmentVariableTarget]::User) Replace Your_GitHub_Token with your actual GitHub token.

2. Update `.gitignore` in Project Root

Exclude .npmrc in your .gitignore file: *.npmrc

3. Create a `.npmrc` File in the Root of the Project

Navigate to your project directory and create .npmrc:

cd path\to\your\project
echo "@cdcgov:registry=https://npm.pkg.github.com/" > .npmrc
echo "//npm.pkg.github.com/:_authToken=%NODE_AUTH_TOKEN%" >> .npmrc

4. Login to NPM with GitHub Registry

npm login --registry=https://npm.pkg.github.com/ --scope=@cdcgov --always-auth

When prompted, enter your GitHub username, GitHub token as the password, and your email address.

5. Create and Publish Your NPM Package

Initialize your package (if not already done):

npm init

Set the version according to your format:

npm version 202304.0.0

If you're using Lerna:

lerna version --major 202304

Publish your package:

npm publish --registry https://npm.pkg.github.com/@cdcgov

6. Check Package Access and Status

npm access list packages --scope=@cdcgov
npm access get status @cdcgov/cdc-react

Remember to replace placeholders like path\to\your\project and Your_GitHub_Token with your actual project path and GitHub personal access token.

How to Publish Your REACT NPM Package To GitHub on Ubuntu

To publish an NPM package to GitHub, you will first need to create an NPM account if you haven't already. Once you have an account, you can follow these steps:

Add NODE_AUTH_TOKEN to .bashrc

cd $HOME
nano ~/.bashrc
export NODE_AUTH_TOKEN=$GITHUB_TOKEN
source ~/.bashrc

Update .gitignore in project root to exclude .npmrc
```
*.npmrc
```

Create a .nprc file in the root of the project

cd cdc-react
echo "@cdcgov:registry=https://npm.pkg.github.com/" > .npmrc
echo "//npm.pkg.github.com/:_authToken=$GITHUB_TOKEN" >> .npmrc

Login

npm login --registry=https://npm.pkg.github.com/ --scope=@cdcgov --always-auth --_authToken=<YOUR_GITHUB_TOKEN>

Create your NPM package: Once your repository is created, you can start creating your NPM package. You can do this by running the npm init command in your terminal to create a new package.json file. Then, you can add your code and dependencies as you normally would. For PADE, our NPM Package is stored in the cdc-react folder.

Create a version with the YYYYMMM.RELEASE.PATCH: Example: 202304.0.0
```
npm version 202304.0.0
lerna version --major 202304
```
Publish your package to NPM: To publish your NPM package to the NPM registry, run npm login to log in to your NPM account and authenticate yourself. Then, run npm publish to publish your package to the registry. Make sure to specify the correct version number in your package.json file before publishing.
```
npm access list packages scope:@cdcgov
npm access get status @cdcgov/cdc-react
npm publish -registry https://npm.pkg.github.com/cdcgov --scope=cdcgov
```

More Information

Template Package is maintained by the WCMS / TP team with OADC, in the repo: CDC WCMS Template Repository

Feel free to submit issues to this repo. More information is available here:

-Metrics Guide -Template Package gallery -Template Package gallery: Icons -Template Package gallery: Styles

Troubleshooting

Problem - can't load svg image in react

-Reference Article

Problem - .yarn-metadata.json: Unexpected end of JSON input

This error typically indicates that there was a problem with the installation or caching of a package using Yarn. To resolve this error, you can try the following steps:

Clear the Yarn cache by running the following command:

yarn cache clean

Delete the .yarn-metadata.json file in the rxjs package directory:

sudo rm /usr/local/share/.cache/yarn/v6/npm-rxjs-7.8.0-90a938862a82888ff4c7359811a595e14e1e09a4-integrity/node_modules/rxjs/.yarn-metadata.json

If these steps don't resolve the error, you may need to try updating or reinstalling Yarn itself.

Problem: Unable to connect to GitHub with ssh: @github.com: Permission denied (publickey).

Warning: Permanently added the ECDSA host key for IP address '140.82.114.3' to the list of known hosts. jcbowyer@github.com: Permission denied (publickey). git@github.com: Permission denied (publickey).

Solution:

Check your keys

cd $HOME/.ssh
ls -al

Check that your SSH key has the appropriate permissions. The SSH key should have read-only permissions, which you can set by running the following command:

chmod 400 ~/.ssh/known_hosts

Verify that your SSH key is added to the ssh-agent. You can add your key to the ssh-agent by running the following command:

ssh-add ~/.ssh/known_hosts

Ensure that you have the correct remote URL for your Git repository. You can check the remote URL by running the following command:

git remote -v

If the URL is incorrect, you can update it using the following command:

git remote set-url origin git@github.com:<username>/<repository>.git

Replace with your GitHub username and with the name of your Git repository.

Problem: Division Fails in SASS

Article: Stack Overflow