Getting started in a new project

These are the steps you need to go through to start consuming FancyLib or FancyLab in your frontend project

Using the GitHub NPM Registry Install Fancy Configure Webpack Fancy Context Configure Your Build Pipeline

#Using the GitHub NPM Registry

This project is distributing NPM packages through the GitHub NPM registry. In order to install the packages you need to authenticate your local NPM client against the GitHub registry and set up the @siteimprove NPM scope to use the GitHub registry.

Add the following lines to your user home directory ~/.npmrc:

# Map @siteimprove npm scope to GitHub NPM Registry
@siteimprove:registry=https://npm.pkg.github.com

#GitHub NPM Authentication

Add the following lines to your ~/.npmrc
# Authenticate against GitHub NPM Registry //npm.pkg.github.com/:_authToken=PASTE_AUTH_TOKEN_HERE
Keep the file open, so you can paste in the token you will get in a moment.
Go to create a new GitHub personal access token.
Add a note about what this token will be used for: GitHub NPM registry read-only.
Enable the read:packages scope.
Press Generate token button.
Copy the token value when it has been created
Replace PASTE_AUTH_TOKEN_HERE in ~/.npmrc with your copied token.
Save ~/.npmrc. You are now ready to install packages from GitHub.

#Install Fancy

Run npm install --save @siteimprove/fancylib or npm install --save @siteimprove/fancylab

#Configure Webpack

In order to consume Fancy from Webpack, you might need to configure your Webpack with more loaders than you already have. Your Webpack setup might already have the nessessary configurations, so you might want to just try things out and see if your existing setup already works. We do not recommend adding more configuration than you need.

#Loading JS

Fancy is written in TypeScript, but distributes the compiled JavaScript along with its TypeScript definitions. This is to reduce the workload in the consuming projects and avoid a tight coupling between TypeScript compiler versions between Fancy and consuming projects.

The distributed JavaScript code is as modern as it can be, which currently means we compile with a target version of ES2019. It is up to the individual consuming project to further compile the distributed JavaScript down to the level they need to hit their browser support target.

Here is how you can set up a Webpack loader that loads FancyLib and FancyLab JavaScript and run it through Babel to enable you to compile the target version to your browser support target:

npm install --save-dev babel-loader

const webpackConfig = {
	module: {
		rules: [
			{
				test: /node_modules[/\]@siteimprove[/\]fancy.*.js$/,
				exclude: /node_modules[/\]@siteimprove[/\]fancy.*[/\]node_modules/,
				loaders: ['babel-loader'],
			},
		]
	}
}

In the above example it is assumed that you use an external Babel config file in order to avoid config repetition across multiple Babel loader instances

#Loading CSS

Fancy uses CSS modules with Sass as its source format, but the distribution files are already compiled CSS files, which simplifies bundler setup in the consuming projects.

This is a reduced CSS loading setup with CSS extraction to a static file:

npm install --save-dev mini-css-extract-plugin css-loader

const MiniCssExtractPlugin = require('mini-css-extract-plugin');
const webpackConfig = {
	plugins: [new MiniCssExtractPlugin(
		// Your configuration here
	)],
	module: {
		rules: [
			{
				test: /node_modules[\\/]@siteimprove[\\/]fancy.*\.css$/,
				loaders: [MiniCssExtractPlugin.loader, "css-loader"],
			},
		]
	}
}

It is recommended that you extend the CSS loading pipeline with postcss-loader and extend it with the postcss-preset-env plugin to get the CSS targeted at your browser range configured in .browserslistrc.

#Loading File Assets

Fancy will load asset types that are not CSS or JavaScript, which just need to be included via a normal URL and created as externals files as part of your bundler run. Webpack needs to be configured to be able to deal with these files. For this we use file-loader:

npm install --save-dev file-loader

const webpackConfig = {
	module: {
		rules: [
			{
				test: /node_modules\/@siteimprove\/fancy.*\.(woff|woff2|svg|png|jpg|jpeg|gif)$/,
				loaders: ["file-loader"],
			},
		]
	}
}

#Fancy Context

Fancy provides a React context that must be wrapped at an outer level of where Fancy components are used. For now the context is used to identify the chosen language for translations. The context also inserts an element that applies the global styles from Fancy to all decendendant. The global styles are required to apply things like fonts to Fancy and non-Fancy components inside a Fancy application.

import React from 'react';
import { FancyContext } from '@siteimprove/fancylab';
import "@siteimprove/fancylib/global.css"; // Global styles for general styling

export const App : React.FC = () => {
	return <FancyContext lang="en-US">{'...'}</FancyContext>;
}

#Configure Your Build Pipeline

Exactly as in Configure your NPM client, your CI pipeline needs an authentication token in order to be able to download the fancylib and fancylab packages from the private GitHub package repository.

#Using the Gihub NPM Registry

In order to map the @siteimprove npm scope to the GitHub Package Repository, add an .npmrc at the root of your node project and add the following lines:

# Map @siteimprove npm scope to GitHub NPM Registry
@siteimprove:registry=https://npm.pkg.github.com

#Authenticate your CI client to GitHub packages

In order to authenticate your CI client to GitHub Packages you need an auth token, which you create in the same way as described above for your personal account. To avoid coupling your CI access to any individual person, create the read:packages with the siteimprove GitHub account.

You need to add the token to your CI environments secrets, for examples as GITHUB_PACKAGES_READ_TOKEN.

From here you need to expose that secret in the environment that will end up running your npm install or npm ci command.

Before the npm installation step you need to append the authentication token to your CI working copy of .npmrc:

echo "//npm.pkg.github.com/:_authToken=$GITHUB_PACKAGES_READ_TOKEN" >> .npmrc