@scrippsproduct/scripps-external-component-library v1.0.2-dev.2

Scripps External Component Library

A collection of React components in Storybook for use with ORION related applications. The library can be viewed at Chormatic - External Component Libray. The NPM package can be found here: ORION Component Library.

Getting Started

• clone this repository to a local folder and navigate to that folder
• make sure you are using a Node LTS version of 20.15.0 or higher (it is recommended to use NVM for node version management)
• install dependencies (run npm install)
• run the project (npm run storybook) - this will start a local server on port 6006
  • the script will automatically open the project in a browser tab at https://localhost:6006
  • 6006 is the default port, the script may ask to open on a differnet port if it detects 6006 is already in use

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 -dev
    • current version 0.1.0 => v0.1.1-dev
• 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-dev.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/orion-component-library": "~0.1.1-dev.0")
• if after review futher revisions are required, you will need to change the version number in the package.json file.
  • 0.1.1-dev.0 => 0.1.1-dev.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=dev
• then publish as described previously

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}--.chromatic.com (i.e. https://v0.1.1-dev--6320f9b58155e710d0652e0d.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--6320f9b58155e710d0652e0d.chromatic.com)

Available Scripts

• storybook: compiles and runs the project locally on 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
  • 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
• 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
• 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

Using this library in a local project

This isn't working currently

• run the distribute script (npm run distribute)
• in the package.json of your project link your library dependency to the root folder of this library (i.e. "@scrippsproduct/brightspot-component-library": "file:../brightspot-component-library")
• re-install the dependencies in the local project
• you can now import components from the local library into your project