npm package: @scrippsproduct/brightspot-component-library
Description: React component library for use with Brightspot
Author: Scripps Digital Product Division
Latest version: 0.2.21

# Scripps Brightspot Component Library 

A collection of [React](https://react.dev/) components in [Storybook](https://storybook.js.org/) for use with [Brightspot](https://react.dev/) related applications. The library can be viewed at [Chormatic - Brightspot Component Libray](https://master--6679c238a645ab1079aa43f2.chromatic.com). The NPM package can be found here: [Brightspot Component Library](https://www.npmjs.com/package/@scrippsproduct/brightspot-component-library).

## Getting Started
- clone this repository to a local folder and navigate to that folder
- load the correct version of node (```nvm use```)
- install dependencies (```npm install```) 
- run the project (```npm run storybook```) 

## Adding New Components
This library is setup to handle either tsx or jsx components. 

### Manual Approach
- create a new folder in the components folder corresponding to the name of the component you will be creating.
- inside this folder create 4 new files
    1. index.ts/js - this file will only conatain an import of your component (```import { Example } from './Example'```)
    2. a tsx/jsx file named after the component (```Example.tsx```)
    3. a stories file named after the component (```Example.stories.tsx```)
    4. and a scss module file also named after the component (```Example.module.scss```)
    - if you are using TypeScript you may also wish to create a separate file to define your types (```Example.types.ts```)
    - this is the minimum set of files in this folder, there may be circumstatnces where you will require others
- in order for your component to be available in the package you will need to export it from ```src/index.ts``` (```export { Example } from './components/Example'```)

### Automated Approach
- there is a helper script to help facilitate creating new components
  - use the command ```npm run create-component {component name} {component file type tsx/jsx}``` (i.e. ```npm run create-component newComponent tsx```)
  - a new folder with the component name will be created in the ```components``` folder and it will contain a base set of new files that contain some boilerplate code

## Publishing prerelease versions for testing or review
- create a new brach off of the ```master``` branch
    - name this branch by incrementing the patch version number by 1 and prefixing with a ```v``` and followed by a prerelease id of ```-alpha``` 
      - current version ```0.1.0``` => ```v0.1.1-alpha```
- update the version number of the main ```package.json``` file to reflect the number used to create the branch (i.e. ```"version": "0.1.1-alpha.0"```) and commit this update to the branch
- you may merge any branches that contain updates for this version, or create your updates directly on this branch
- push your changes to this branch 
- to publish this version run ```npm build``` and then ```npm publish```
    - note that if you use an authenticator app as your method of 2FA you can add the code directly in the command line by using the ```otp``` option: ```npm publish --otp={code from app}```
- once the version is published it can be used in a project by using the version number you created (i.e. ```"@scrippsproduct/scripps-news-component-library": "~0.1.1-alpha.0"```)
- if after review futher revisions are required, you will need to change the version number in the package.json file. 
  - ```0.1.1-alpha.0``` => ```0.1.1-alpha.1``` (this is neccessay because NPM will not allow a package to be published with the same version number)
  - if all of your changes have been commited this may also be accomplished by running ```npm run version prerelease --preid=alpha```
- then publish as described previously 
- we try to follow the [Semantic Versioning 2.0.0](https://semver.org/) standard 

## Publishing a new patch, minor or major version
- create a new branch from ```master``` and name it with the new version number (i.e. a new patch version ```v0.1.2```)
- merge all updates to be included in the new version to this new branch
- update the version number in the main ```package.json``` file (```"version": "0.1.2"```)
- commit the changes & push the new branch
- make a merge request to have this branch merged with ```master``` and published
    - in your merge request include a list of the changes from the previous version

## Publishing the library to Chromatic for reviewers
- run the chromatic script (```npm run chromatic```)
    - this will create a new build on Chromatic from the current active branch
- if you run into visual discrepencies those will need to be approved prior to reviewers being able to view the new build
- once the build has passed approval direct reviewers to the project on Chromatic by using your branch name in this URL: https://{branch name here}--6679c238a645ab1079aa43f2.chromatic.com (i.e. ```https://v0.1.1-alpha--6679c238a645ab1079aa43f2.chromatic.com```)  
    - note that since this is a URL if you use a forward slash in your branch (i.e. ```feature/something```) the forward slash will need to be a dash (-) in the URL (```https://feature-something--6679c238a645ab1079aa43f2.chromatic.com```)


## Available Scripts
- ```storybook```: compiles and runs the project locally on [localhost:6006](http://localhost:6006)
- ```build```: compiles TypeScript and Javascript files into the ```dist``` folder
    - the files produced are ready to be published as a new version
    - the ```dist``` folder is the only folder that is included in the published package
- ```chromatic```: will create a new build version on [Chromatic](https://www.chromatic.com/)
    - this process will run a visual test of all components, if there are any discrepancies they will have to be approved before the new version will be available to view
- ```build-storybook```: builds a production ready version of the project for hosting the library on a server 
    - this can be useful for debugging build errors while trying to build to Chromatic
- ```create-component```: requires 2 paramters, 1) the component name 2) the component file type (tsx/jsx), will create a new component folder with boilerplate files