@servicetitan/anvil2-ext-common

Anvil2 Extended Common

The Anvil2 Extended Common library is an open contribution area for components, hooks, and other code that extends Anvil2. This is maintained by the larger ServiceTitan engineering organization with support from the Design System team.

Getting Started

Installation

We recommend installing the Common package by running the following npm command (or the equivalent yarn/pnpm command) in your project folder:

npm install @servicetitan/anvil2-ext-common

[!NOTE] This package requires @servicetitan/anvil2 as a peerDependency, so make sure that is installed as well, and meets the version requirement in this package's package.json.

Usage

Components and hooks can be imported as named exports from the package root:

import { useConfirmDialog } from "@servicetitan/anvil2-ext-common";

Contribution Guide

This extended common library is meant to be a place for contributions that extend the Anvil2 library, but that don't necessarily make sense to live inside of Anvil2. Do you have a wrapper to connect a component to MobX or formstate or to a specific backend API? Do you have a shorthand to reduce the boilerplate for one of your common use cases? This is the place for those kinds of contributions!

This library can also be used as a place to test new ideas and features that are proposed to be added to Anvil2 in the future, but that need more validation or testing. Code in the common library is not required to be 100% stable to allow for these kind of experimental contributions and to serve as a more open area for testing ideas.

The Design System team intends to give guidance and help with maintaining contributions here, but contributions to this package aren't intended to meet the same standards as Anvil2 code.

Prerequisites

This monorepo requires Node >= 20 and pnpm >= 9.
To install pnpm, please follow the installation instructions at: https://pnpm.io/installation

Setting up your local repo

Install the dependencies from the top-level project root directory:

pnpm install

To make sure everything is installed and working properly, we recommend running a build. This command will also build Anvil2 and its dependencies, so it might take a few minutes:

pnpm build:common

Development

To run our Storybook, you can use the following script from the root of the repo:

pnpm storybook:common

Our ext-common Storybook will be hosted at http://localhost:8008/.

[!NOTE] For more information about using Storybook, see their docs.

Adding a new component or hook

Directory structure

- src
  - components
    - MyNewComponent
      - internal
        - SomeInternalCode.ts
      - MyNewComponent.tsx
      - MyNewComponent.stories.tsx
      - MyNewComponent.test.tsx
      - index.ts
    index.ts

To add a new component, you would start by added a new folder in the src/components directory for your component. Inside that folder, in addition to the files for your component, you'll want to add an index.ts file where you export everything you want to be publicly accessible (component, proptypes, context, etc). Code that is not intended to be public can be organized into an internal subdirectory.

Then in the src/components/index.ts file, you'll want to add the export for your new component to make sure it gets exported along with all the other components.

export * from "./SomeExistingComponent";
export * from "./MyNewComponent";

To add new stories to the existing Storybook, you'll need to add a file that ends in *.stories.tsx or *.mdx.

To add new unit tests to the existing Vitest run, you'll need to add a file that ends in *.test.tsx or test.ts.

Adding a new top-level folder in src

To add a new top-level folder in the src directory works very similarly, just another level higher. You would create a new folder under src:

- src
  - components
  - hooks
  - mynewcategory
  index.ts

...and then add your new folder's exports to the src/index.ts file:

export * from "./components";
export * from "./hooks";
export * from "./mynewcategory";

Making a pull request

Changesets

We use Changesets to create release notes and manage our release versioning.

When you are ready to create a PR to release a change to this package, run:

pnpm changeset

Follow the steps and use appropriate semantic version for your change.

Changeset message format

Please format your changelog with name of the relevant components, hooks, or other code in brackets at the start of the changelog, such as:

---
"@servicetitan/anvil2": patch
---

[TextField] Update padding for `TextField` `prefix` and `suffix`

For more details, see our internal docs on changeset formatting.

Other useful scripts

From the root of the monorepo, you can run the following to run scripts specifically for the common library:

pnpm build:common
pnpm lint:common   # run ESLint
pnpm test:common   # run Vitest
pnpm clean         # clear build outputs
pnpm nuke          # clear build outputs and node_modules