Documentation

• JustiFi Web Component Documentation

Useful Commands

• pnpm build - Build all packages, including the Storybook site
• pnpm dev - Run all packages locally and preview with Storybook
• pnpm test - Run all tests
• pnpm test:watch - Run all tests in watch mode
• pnpm lint - Lint all packages
• pnpm changeset - Generate a changeset
• pnpm clean - Clean up all node_modules and dist folders (runs each package's clean script)

Turborepo

Turborepo is a high-performance build system for JavaScript and TypeScript codebases. It was designed after the workflows used by massive software engineering organizations to ship code at scale. Turborepo abstracts the complex configuration needed for monorepos and provides fast, incremental builds with zero-configuration remote caching.

Using Turborepo simplifies managing your design system monorepo, as you can have a single lint, build, test, and release process for all packages. Learn more about how monorepos improve your development workflow.

Apps & Packages

This Turborepo includes the following packages and applications:

• apps/docs: Component documentation site with Storybook
• apps/component-examples: Simple component example files
• packages/webcomponents: JustiFi component library

Each package and app is 100% TypeScript. Workspaces enables us to "hoist" dependencies that are shared between packages to the root package.json. This means smaller node_modules folders and a better local dev experience. To install a dependency for the entire monorepo, use the -w workspaces flag with pnpm add.

This example sets up your .gitignore to exclude all generated files, other folders like node_modules used to store your dependencies.

Compilation

Running pnpm build from the root of the Turborepo will run the build command defined in each package's package.json file. Turborepo runs each build in parallel and caches & hashes the output to speed up future builds.

For webcomponents, the build command is the following:

stencil build --docs

Stencil compiles src/index.tsx, which exports all of the components in the library, into both ES Modules and CommonJS formats as well as their TypeScript types. The package.json for webcomponents then instructs the consumer to select the correct format:

{
  "name": "@justifi/webcomponents",
  "version": "x.y.z",
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/types/index.d.ts",
}

Run pnpm build to confirm compilation is working correctly. You should see a folder webcomponents/dist which contains the compiled output.

webcomponents
└── dist
    ├── index.d.ts  <-- Types
    ├── index.js    <-- CommonJS version
    └── index.mjs   <-- ES Modules version

Components

Each file inside of webcomponents/src/components is a component inside our component library. For example:

Storybook

Storybook provides us with an interactive UI playground for our components. This allows us to preview our components in the browser and instantly see changes when developing locally. This repo is set up to:

• Use Vite to bundle stories instantly (in milliseconds)
• Automatically find any stories inside the stories/ folder
• Support using module path aliases for imports
• Write MDX for component documentation pages

This project includes a few helpful Storybook scripts:

• pnpm dev: Starts Storybook in dev mode with hot reloading at localhost:6006
• pnpm build: Builds the Storybook UI and generates the static HTML files
• pnpm preview-storybook: Starts a local server to view the generated Storybook UI

Versioning & Publishing Packages

This project uses Changesets to manage versions, create changelogs, and publish to npm. It's preconfigured so you can start publishing packages immediately.

Generating the Changelog

To generate your changelog, run pnpm changeset locally:

1. Which packages would you like to include? – This shows which packages and changed and which have remained the same. By default, no packages are included. Press space to select the packages you want to include in the changeset.
2. Which packages should have a major bump? – Press space to select the packages you want to bump versions for.
3. If doing the first major version, confirm you want to release.
4. Write a summary for the changes.
5. Confirm the changeset looks as expected.
6. A new Markdown file will be created in the changeset folder with the summary and a list of the packages included.

Running component example files

This project offers the ability to render the components in simple example files that will help simulate real world usage.

1. Clone this project to your local machine
2. Once installed, run pnpm install && pnpm build to build the component library's latest version.
3. Component example files can be loaded by using pnpm dev with a corresponding file name - such as pnpm dev:checkout