Frontend Library Template

=========================

Production Readiness Document

Overview

This repository serves as a starting point for creating frontend libraries within our organization. It provides a basic structure and configuration for building, testing, and documenting reusable UI components, utilities, and other frontend functionality.

Getting Started

To use this template, follow these steps:

• Message @SRE in the Slack #devops channel: @sre I need a new frontend library template repo created called <your repo name>, thanks!
• After the repo is set up, clone it to your local machine: git clone <repo ssh url>
  • Note: Replace <your repo name> and <repo ssh url> with the correct name/url.
• Update the CODEOWNERS file to reflect who should be able to approve and manage code (update the * line).
• Update the package.json file to reflect your library's metadata, such as its name, version, and description.
• Remove any unnecessary files, directories, or dependencies you don't need for your library.
• You will likely need to make adjustments to the versions of the dependencies in package.json to match the versions you need or what we are currently using.

Remember, this is just a starting point!

Directory Structure

The repository is organized into the following directories and files:

Directories:

• src: Contains the source code for your library, including components, utilities, and tests.
• types: Defines type declarations for your library.
• .storybook: Holds Storybook configuration files.
• .vscode: Includes VS Code settings and configurations for the workspace.
• .yarn: The Yarn binary that is used by the repo.
• dist: The output directory for compiled and bundled code. (This is not checked in to the repo)

Root Files:

• gitlab-ci.yml: The CI/CD configuration file. This mainly pulls in a CI/CD template, and this file should not be modified.
• biome.json: The biome configuration file. If you want or need to make adjustments to linting or formatting, this is where you'd do it.
• tsconfig.json: The TypeScript configuration file.
• tsconfig.types.json: The TypeScript configuration file for type generation.
• vite.config.ts: The Vite configuration file (the bundler).
• CODEOWNERS: The file that defines who should be able to approve and manage code.
• package.json: The package file that defines the library's metadata and dependencies.
• .gitignore: The file that defines which files and directories should be ignored by Git. By default, it should ignore pretty much everything you need, but if you need to ignore something new or additional, you can add it to this file.

The rest of the files and folders, if any, should generally not be modified and should be left as is unless you know what you are doing.

Build and Test

The repository includes scripts for building, testing, and linting your code. You can run these scripts using the following commands:

• check-all: Runs all the checks (linting, formatting, types, etc.) on your code.
• check-types: Runs the type checker on your code.
• check-format: Runs the code formatter on your code.
• check-lint: Runs the linter on your code.
• fix-all: Runs all the fixers (formatting, linting, etc.) on your code.
• fix-format: Runs the code formatter on your code and fixes fixable problems.
• fix-lint: Runs the linter on your code and fixes fixable problems.
• fix-imports: Runs the linter fixer on your code and fixes fixable import problems.
• build: Builds your library using Vite.
• build-types: Builds your library's type declarations.
• test: Runs your library's tests.
• test-coverage: Runs your library's tests with code coverage.
• storybook: Starts the Storybook server.
• build-storybook: Builds the Storybook documentation static files (for deployment).

Storybook

Storybook is integrated into this repository for easy component development and testing. You can run Storybook using the following command:

yarn storybook: Starts the Storybook development server.

CI/CD

The repository includes a .gitlab-ci.yml file that defines a basic CI/CD pipeline. This pipeline builds, tests, and deploys your library to a registry.

Publishing Process

The publishing process is set up to facilitate both a standard release as well as alpha releases. Follow the steps below.

Publishing a tagged (main) release

• Create and publish the initial tag. Do this after you have completed the getting started steps (this is important as it won't work otherwise). Just create a new tag (GitLab repo > Tags > Create). You can label it 0.0.1.
• Open the tag's pipeline, and after it finishes, you will have a manual job you can run called deploy with a task of publish-internal. Click the play/run button to run this job, which will publish your library to the internal registry.
• For subsequent releases, you will simply create a tag, and then in the tags pipeline, use the deploy manual task like the previous step to publish the new tagged version.

At this point, you will have a published library that can be installed. Generally, this will be from @tcn-internal/<your repo name>. (e.g., yarn add @tcn-internal/my-library)

Publishing an alpha release

• To create alpha branches, you must have published at least one main version first (the steps above).
• Once that is done, to publish alpha branches, you can use the deploy step, publish-branch-internal job available on MR, master, and all other non-tag branches, which will publish an alpha version of your library to the internal registry.
• When it's done with that job, you can open the job, and at the bottom of the log, you will find the exact alpha branch name you can use to install. It will look like this: @tcn-internal/[email protected]
• You can also install the latest alpha by just using the branch name: @tcn-internal/my-library@alpha, which will install the latest alpha version.

This is nice because you can publish an alpha version from your MR, then go install and test it out in another repo before doing an actual main tagged release.

Deploying Storybook static

If you want to publish your Storybook so that it is available on the web, follow these steps:

• Note: This is only available on non-tag branch pipelines.

• On your branch pipeline, look for the storybook-deploy task under the deploy job and click the play/run button to run it.

• Once successfully completed, your Storybook will be published and publicly accessible at:

  • https://storage.googleapis.com/sb-tcncloud-com/YOUR-LIBRARY-NAME/index.html
    • For example: https://storage.googleapis.com/sb-tcncloud-com/wfm-skills-profiles/index.html

  AND

  • https://sb-tcncloud-com.storage.googleapis.com/YOUR-LIBRARY-NAME/index.html
    • For example: https://sb-tcncloud-com.storage.googleapis.com/wfm-skills-profiles/index.html

Best Practices

When using this template, please follow these best practices:

• Keep your code organized and modular, utilizing ports/adapters, domains, and presenters.
• Write meaningful tests that don't test for things already covered by TypeScript or external library tests.
• Use Storybook to develop and test your components.
• Keep your documentation up to date.