@boulevard/blvd-ui v1.0.0-beta.48

@boulevard/blvd-ui

Welcome to Boulevard's component library. This project provides the components and tools necessary to build quality apps in the Boulevard Ecosystem.

Features

• React - The JS Framework it is built with.
• Rollup - Bundling the package for distribution. (Official Plugins)
• Sass - Styling of the components.
• TypeScript - Type safety and more confidence in component API's.
• Storybook to help you create and show off your components.
• Chromatic enabling Visual Regression Testing.

Storybook Addons

• a11y - Check accessibility of components.
• actions - Display data received by event handlers in Storybook.

Installing and authorizing the package

To install this package you will need a GitHub access token. To generate a new GitHub access token with the appropriate scopes for installing this package follow these steps.

1. Go to https://github.com/settings/tokens
2. Click the Generate new token button
3. Make sure the following scopes are selected (see image below) and then click Generate token. You may want to give your token a name so that you know it is for installing packages. Also, if you think you will be publishing the blvd-ui package you will also want to select the write:packages and delete:packages scopes.

4. Once your token is created make sure you enable SSO for your token. If you made a mistake in the last step and need to edit your token, remember that you will need to re-enable SSO for a token after its scopes have been edited.
5. From the command line authenticate with the GitHub registry using the token you just created:

$ npm login --registry=https://npm.pkg.github.com
> Username: {{USERNAME}}
> Password: {{TOKEN}} !!!This is not your GitHub password but the token you just created!!!
> Email: {{PUBLIC-EMAIL-ADDRESS}}

After completing step 5 you will be able to install private packages from our GitHub registry. To avoid having to authenticate with the registry in the future you can add the following to a .npmrc file in your home directory

//npm.pkg.github.com/:_authToken={{TOKEN}}

Authenticating with npm from the command line may actually create this file with this line for you. Also, creating this file manually may allow you to skip authenticating from the command line entirely. If you’re confused about step 5 you can find more info here

Development

Testing

yarn test

Linting

yarn lint

Storybook (live reload development)

yarn storybook

Publishing

Package distribution

First make sure that you've updated the version field in package.json to reflect your changes to the package (major.minor.patch) in the private GitHub registry. Then run:

# Publish the package
yarn distribute

Static Storybook site

# Build the static storybook site
yarn build-storybook

Component Usage

Note: The css for this library is extracted into its own file. You will need to import it for the components to render correctly. @boulevard/blvd-ui/index.css

import React from "react";
import { Button } from "@boulevard/blvd-ui";

export const App = (): JSX.Element => (
  <div>
    <h1>My app!</h1>
    <Button theme="primary">Hello world!</Button>
  </div>
);

Using internal SASS variables in TS/JS

For example, let's say you installed @boulevard/blvd-ui into your project. To use the exported scss variables in JS or TS you would do the following:

import { borderRadiusMedium, spacing } from "@boulevard/blvd-ui/design-tokens";

console.log(borderRadiusMedium); // "0.25rem"
console.log(spacing[1]); // "0.125rem"

Installing locally & testing within another package

Let's say you have another project (Dashboard) on your machine that you want to try installing the component library into it without having to first publish the component library. In the Dashboard directory, you can run:

# Clone the component libary.
git clone git@github.com:Boulevard/blvd-ui.git

# cd into blvd-ui and install dependencies then run the build.
cd blvd-ui
yarn
yarn build

# cd into the project you want to use this local copy in. (Dashboard in this case)
cd ../Dashboard

# Add the library as a local dependency.
yarn add link:../blvd-ui/build

which will install the local component library as a dependency in Dashboard, overriding the "@boulevard/blvd-ui": "^x.x.x" entry with "@boulevard/blvd-ui": "../blvd-ui/build" in your package.json. Your components can then be imported and used. DO NOT commit the changes to the package.json or yarn.lock files.

To reinstall the package from the registry, simply run yarn add @boulverad/blvd-ui again.