@servicetitan/docs-uikit 31.5.1 → 32.0.0

package/docs/BREAKING_CHANGES.mdx

@@ -2,6 +2,24 @@
 title: BREAKING CHANGES
 ---
 
+## v32.0.0
+
+### [@servicetitan/startup](./startup)
+
+:::caution
+This breaking change affects local development, even if you do not update the `@servicetitan/startup` dependency directly. On a clean install, the standard bootstrap script runs the latest version of `startup`, which automatically removes hard-coded tokens from `.npmrc` files.
+:::
+
+Removed support for hard-coded npm tokens in `.npmrc` files. The new `startup install` removes hard-coded authentication tokens from project `.npmrc` files and, in development environments, automatically adds a token to npm's per-user configuration that grants access to ServiceTitan's private packages.
+
+Projects that previously relied on hard-coded tokens must update their Github and Teamcity workflows to instead use the organization secret as described in the [startup install documentation](./startup/install#configuring-npm-token-in-ci):
+
+- Option 1: Inject the organization secret into `.npmrc`.
+- Option 2: Configure `.npmrc` to get the organization secret from an environment variable.
+
+**Why this change?**  
+Two recent incidents mandated that we revoke the shared token that grants access to ServiceTitan's private packages. By removing hard-coded tokens, ServiceTitan can more easily and seamlessly rotate or revoke tokens, improving security and reducing friction for developers.
+
 ## v31.0.0
 
 ### [@servicetitan/startup](./startup)
@@ -63,14 +81,13 @@ title: BREAKING CHANGES
 
 ### [@servicetitan/ajax-handlers](./ajax-handlers)
 
-- Changed [**withMicroservice**](./ajax-handlers#parameters) arguments to a single options object.
+- Changed [**withMicroservice**](./ajax-handlers/with-microservice#parameters) arguments to a single options object.
 
 ## v24.0.0
 
 ### [@servicetitan/startup](./startup)
 
 - Upgraded **Typescript** from v4 to v5, which adds correctness improvements that will reveal previously undetected ambiguities. In particular,
-
     - Type checks for enums are stricter because all **enum** values get their own type
     - **string** and **boolean** values aren't implicitly converted to numbers. Use the `+` operator to explicitly convert values to numbers in mathematical expressions. (e.g., `return +str > 42;`)
 

package/docs/ajax-handlers/ajax-handlers.mdx

@@ -0,0 +1,12 @@
+---
+title: AJAX Handlers
+---
+
+#### [CHANGELOG (@servicetitan/ajax-handlers)](https://github.com/servicetitan/uikit/blob/master/packages/ajax-handlers/CHANGELOG.md)
+
+`@servicetitan/ajax-handlers` provides utilities for handling AJAX requests, authentication, and response processing in ServiceTitan applications. It includes automatic date parsing, authentication wrappers for protected resources, and comprehensive error handling.
+
+## API
+
+- [withMicroservice](./with-microservice.mdx) - Use `withMicroservice` to wrap components and authenticate requests to protected resources with support for Bearer and Token Server authentication.
+- [initAjaxHandlersParseDates](./init-ajax-handlers-parse-dates.mdx) - Use `initAjaxHandlersParseDates` to automatically transform date strings in axios responses into JavaScript Date objects.

package/docs/ajax-handlers/init-ajax-handlers-parse-dates.mdx

@@ -0,0 +1,74 @@
+---
+title: initAjaxHandlersParseDates
+---
+
+`initAjaxHandlersParseDates` is a function that automatically transforms date strings in axios responses into JavaScript Date objects. This eliminates the need for manual date parsing throughout your application.
+
+## Usage
+
+Call this function once in your application's initialization code, typically before making any axios requests:
+
+```tsx
+import { initAjaxHandlersParseDates } from '@servicetitan/ajax-handlers';
+
+// Initialize date parsing for all axios responses
+initAjaxHandlersParseDates();
+```
+
+## How It Works
+
+The function adds a response transformer to the global axios defaults that:
+
+1. Automatically detects and parses date strings in response data
+2. Recursively traverses objects and arrays to find date strings
+3. Preserves other data types unchanged (including Blobs)
+4. Handles parsing errors gracefully by returning the original data
+
+## Supported Date Formats
+
+The parser recognizes two date formats commonly used in APIs:
+
+### ISO 8601 Format
+
+Supports standard ISO date strings with optional time zones and milliseconds:
+
+- `2024-03-15T10:30:45Z`
+- `2024-03-15T10:30:45.123Z`
+- `2024-03-15T10:30:45+05:00`
+- `2024-03-15T10:30:45.789-08:00`
+
+### .NET JSON Date Format
+
+Supports the legacy .NET JSON date format:
+
+- `/Date(1710504645000)/`
+- `/Date(1710504645000-0800)/`
+- `/Date(-62135596800000)/` (negative timestamps for dates before 1970)
+
+## Example
+
+```tsx
+import axios from 'axios';
+import { initAjaxHandlersParseDates } from '@servicetitan/ajax-handlers';
+
+// Initialize date parsing once
+initAjaxHandlersParseDates();
+
+// Now all axios responses will have dates automatically parsed
+const response = await axios.get('/api/users/123');
+
+// response.data might look like:
+// {
+//   id: 123,
+//   name: 'John Doe',
+//   createdAt: Date object (not a string!),
+//   lastLogin: Date object (not a string!),
+//   metadata: {
+//     updatedAt: Date object (not a string!)
+//   }
+// }
+
+// You can immediately use Date methods
+console.log(response.data.createdAt.getFullYear());
+console.log(response.data.lastLogin.toLocaleDateString());
+```

package/docs/{ajax-handlers.mdx → ajax-handlers/with-microservice.mdx}

@@ -1,15 +1,11 @@
 ---
-title: AJAX Handlers
+title: withMicroservice
 ---
 
-#### [CHANGELOG (@servicetitan/ajax-handlers)](https://github.com/servicetitan/uikit/blob/master/packages/ajax-handlers/CHANGELOG.md)
-
-## withMicroservice
-
 `withMicroservice` is a higher-order function that wraps a component and authenticates
 its requests to protected resources.
 
-### Usage
+## Usage
 
 The best way to use `withMicroservice` is to wrap the component in the ES module body. E.g.,
 
@@ -54,7 +50,7 @@ const App = () => {
 }
 ```
 
-### Parameters
+## Parameters
 
 `withMicroservice` accepts an object with the following properties:
 
@@ -70,27 +66,27 @@ const App = () => {
 | `preAuthenticateCallback` | `(error?: any) => void`             | (optional) callback to call after pre-authentication succeeds or fails. If pre-authentication fails, the error is passed to the first parameter of the callback.                      |
 | `tokens`                  | `Symbol[]`                          | (optional) symbols to use to provide `baseURL` to autogenerated API services and child components                                                                                     |
 
-#### authAdapter{#auth-adapter}
+### authAdapter{#auth-adapter}
 
 Use `authAdapter` to select the authentication scheme. One of,
 
-| Value        | Description                                                                                                                                       |
-| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
-| "bearer"     | **Bearer** authentication sends the bearer token returned by `authURL` in the **Authorization** header of requests. Uses BearerTokenAuth adapter. |
-| "token"      | **Token** authentication uses the Token Server's "silent login" protocol to add secure cookies to requests. Uses TokenServerAuth adapter.         |
+| Value                                               | Description                                                                                                                                       |
+| :-------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
+| "bearer"                                            | **Bearer** authentication sends the bearer token returned by `authURL` in the **Authorization** header of requests. Uses BearerTokenAuth adapter. |
+| "token"                                             | **Token** authentication uses the Token Server's "silent login" protocol to add secure cookies to requests. Uses TokenServerAuth adapter.         |
 | `(context: WithMicroserviceContext) => AuthAdapter` | Custom authentication uses the adapter returned by a function to decorate requests.                                                               |
 
 See [Authentication Adapters](#authentication-adapters) for more information.
 
-#### authUrl
+### authUrl
 
 The authentication endpoint for protected resources.
 
--   For **Bearer** authentication, this is the endpoint that returns the bearer token to send in **Authorization** headers. Defaults to `${baseURL}/auth`.
+- For **Bearer** authentication, this is the endpoint that returns the bearer token to send in **Authorization** headers. Defaults to `${baseURL}/auth`.
 
--   For **Token server** authentication, this is the "silent login" endpoint. Defaults to `${baseURL}/bff/silent-login`.
+- For **Token server** authentication, this is the "silent login" endpoint. Defaults to `${baseURL}/bff/silent-login`.
 
-#### preAuthenticate{#pre-authenticate}
+### preAuthenticate{#pre-authenticate}
 
 Controls when authentication happens:
 
@@ -101,9 +97,9 @@ Controls when authentication happens:
 
 When using Token Server authentication, authentication is always performed after the component is loaded and this value is ignored.
 
-#### tokens
+### tokens
 
-The main purpose of `tokens` is to [provide](./react-ioc#provide) the `baseURL` to autogenerated API services.
+The main purpose of `tokens` is to [provide](../react-ioc#provide) the `baseURL` to autogenerated API services.
 For example,
 
 ```tsx
@@ -138,11 +134,11 @@ const Component = () => {
 }
 ```
 
-### Authentication Adapters{#authentication-adapters}
+## Authentication Adapters{#authentication-adapters}
 
 `withMicroservice` uses authentication adapters in order to perform authentication in different ways depending on your needs.
 
-#### BearerTokenAuth
+### BearerTokenAuth
 
 The default adapter is the `BearerTokenAuth` adapter. When authentication occurs, a request is sent to the `authURL` in order to retrieve a token. Then any requests made using the `baseURL` will add the `Authorization: Bearer ...` header with the stored token.
 
@@ -156,7 +152,7 @@ const App = withMicroservice({
 });
 ```
 
-#### TokenServerAuth{#token-server-auth}
+### TokenServerAuth{#token-server-auth}
 
 The `TokenServerAuth` adapter allows you to authenticate with a backend that is using the `ServiceTitan.Ium.Bff` NuGet package ([see TokenServer documentation for details](/docs/projects/ium/tokenserver-new-app-integration/)).
 
@@ -177,8 +173,8 @@ const App = withMicroservice({
 ```tsx title="Custom adapter"
 const options: TokenServerAuthOptions = {
     authInfoURL: '/custom/authinfo',
-    onError: (defaultErrorHandler) => {
-        console.error('There was an error');
+    onError: (defaultErrorHandler, error) => {
+        console.error(error, error.data);
         defaultErrorHandler();
     },
 };
@@ -189,12 +185,20 @@ const App = withMicroservice({
 });
 ```
 
-##### TokenServerAuthOptions
-| Name          | Type                                         | Description                                                                                                                                                                                  |
-| :------------ | :------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `authInfoURL` | `string`                                     | (optional) URL to fetch authentication parameters from. Defaults to `'/bff/authinfo'`.                                                                                                       |
-| `onError`     | `(defaultErrorHandler: () => void) => void;` | (optional) Callback to call when an error occurs during authentication. Defaults to reloading the page a maximum of 1 time. First parameter is a function to call the default error handler. |
+#### TokenServerAuthOptions
+
+| Name          | Type                                                       | Description                                                                                                                 |
+| :------------ | :--------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------- |
+| `authInfoURL` | `string`                                                   | (optional) URL to fetch authentication parameters from. Defaults to `'/bff/authinfo'`.                                      |
+| `onError`     | `(defaultErrorHandler: () => void, error: Error) => void;` | (optional) Callback to call when an error occurs during authentication. Defaults to reloading the page a maximum of 1 time. |
+
+The `onError` callback is passed the following arguments:
+
+| Name                  | Type       | Description                                                                                        |
+| :-------------------- | :--------- | :------------------------------------------------------------------------------------------------- |
+| `defaultErrorHandler` | `Function` | The default error handler.                                                                         |
+| `error`               | `Error`    | An error object with a `data` property that contains the data associated with the failure, if any. |
 
-### Authorization
+## Authorization
 
 `withMicroservice` currently only assists with performing authentication for requests of protected resources. There are currently no plans to implement authorization until we see concrete Token Server usage examples by product teams. If you find that having any sort of implementation for authorization would be helpful, especially in regards to Token Server implementation, please bring any ideas or discussions to the Frontend Platform team's attention so that we can create a platform solution.

package/docs/datadog-rum.mdx

@@ -0,0 +1,133 @@
+---
+title: DataDog RUM
+---
+
+#### [CHANGELOG (@servicetitan/datadog-rum)](https://github.com/servicetitan/uikit/blob/master/packages/datadog-rum/CHANGELOG.md)
+
+[`@servicetitan/datadog-rum`](https://github.com/servicetitan/uikit/tree/master/packages/datadog-rum) helps configure DataDog RUM JS SDK in standalone applications. It enriches RUM events with information useful for application and MFE monitoring, and troubleshooting.
+
+## Configuration snippet
+
+```tsx
+import { beforeSend, DatadogProvider } from '@servicetitan/datadog-rum';
+import { datadogRum } from '@datadog/browser-rum';
+
+const isEnabled = /.*go\d*\.servicetitan\.com/.test(window.location.hostname);
+
+if (isEnabled) {
+    datadogRum.init({
+        applicationId: '<APPLICATION_ID>',
+        clientToken: '<CLIENT_TOKEN>',
+        site: 'datadoghq.com',
+        service: '<SERVICE_NAME>',
+        env: '<ENV_NAME>',
+        version: '<APPLICATION_VERSION>',
+        sessionSampleRate: 100,
+        sessionReplaySampleRate: 0,
+        defaultPrivacyLevel: 'mask-user-input',
+        beforeSend: beforeSend(),
+    });
+}
+
+const Root = () => {
+    const user = useCurrentUser(); // application-specific hook that identifies the user
+
+    return (
+        <DatadogProvider isEnabled={isEnabled} user={user}>
+            <Application />
+        </DatadogProvider>
+    );
+};
+```
+
+## DatadogProvider
+
+`DatadogProvider` is a higher-order component that supplies RUM SDK with:
+
+- Information about the user session
+- Sanitized view event names (`@view.name`) when hash-based routing is used
+
+### Usage
+
+Wrap your application with `DatadogProvider` close to the root. E.g.,
+
+```tsx
+import { DatadogProvider } from '@servicetitan/datadog-rum';
+
+const Root = () =>
+    return (
+        <DatadogProvider isEnabled={isEnabled} user={user}>
+            ...
+        </DatadogProvider>
+    );
+};
+```
+
+If your application uses hash-based routing, `DatadogProvider` should be placed inside `HashRouter`. E.g.,
+
+```tsx
+import { HashRouter } from 'react-router-dom';
+import { DatadogProvider } from '@servicetitan/datadog-rum';
+
+const Root = () => {
+    return (
+        <HashRouter>
+            <DatadogProvider isEnabled={isEnabled} user={user} options={{ hashRouting: true }}>
+                ...
+            </DatadogProvider>
+        </HashRouter>
+    );
+};
+```
+
+### Parameters
+
+| Name        | Type      | Description                                 |
+| :---------- | :-------- | :------------------------------------------ |
+| `isEnabled` | `boolean` | Enables DD RUM instrumentation              |
+| `user`      | `User`    | (optional) User session information         |
+| `options`   | `Options` | (optional) Additional configuration options |
+
+#### `User`
+
+| Name            | Type                           | Description                          |
+| :-------------- | :----------------------------- | :----------------------------------- |
+| `id`            | `string`                       | User ID                              |
+| `[key: string]` | `string \| number \| string[]` | (optional) Arbitrary user attributes |
+
+#### `Options`
+
+| Name          | Type      | Description                                 |
+| :------------ | :-------- | :------------------------------------------ |
+| `hashRouting` | `boolean` | Sanitizes view names for hash-based routing |
+
+## `beforeSend`
+
+`beforeSend` is a callback function for enriching RUM events. Supported functionality:
+
+- Adds MFE name and version for error and resource events coming from MFEs (`@error.service`, `@resource.service`, `@error.version`, and `@resource.version`)
+- Adds Cloudflare Ray ID for resource events (`@resource.cfRay`)
+
+### Usage
+
+```ts
+import { beforeSend } from '@servicetitan/datadog-rum';
+import { datadogRum } from '@datadog/browser-rum';
+
+const isEnabled = /.*go\d*\.servicetitan\.com/.test(window.location.hostname);
+
+if (isEnabled) {
+    datadogRum.init({
+        applicationId: '<APPLICATION_ID>',
+        clientToken: '<CLIENT_TOKEN>',
+        site: 'datadoghq.com',
+        service: '<SERVICE_NAME>',
+        env: '<ENV_NAME>',
+        version: '<APPLICATION_VERSION>',
+        sessionSampleRate: 100,
+        sessionReplaySampleRate: 0,
+        defaultPrivacyLevel: 'mask-user-input',
+        beforeSend: beforeSend(), // <--beforeSend() returns handler that enriches events
+    });
+}
+```

package/docs/startup/install.mdx

@@ -2,6 +2,9 @@
 title: install
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 Installs project dependencies.
 
 Use this command instead of plain `npm install` to guarantee that all packages are installed correctly and any necessary post-install steps are performed.
@@ -11,3 +14,151 @@ npx --yes @servicetitan/startup install
 ```
 
 See [package.json in the example project](https://github.com/search?q=repo%3Aservicetitan%2Ffrontend-example+path%3A**%2Fpackage.json+%22startup+install%22&type=code) for how to use `install` in an npm script.
+
+## Options
+
+| Option       | Description                                   |
+| :----------- | :-------------------------------------------- |
+| `--no-token` | Disable configuring npm authentication token. |
+
+## Configuring NPM Token in Development
+
+In development environments, `startup install` automatically configures an npm authentication token that grants access to private ServiceTitan packages. It securely retrieves the token and updates your npm configuration so you can install dependencies without any further setup.
+
+:::caution
+`startup install` detects if it is running in development by checking for standard environment variables set by CI systems (e.g.,`CI` and `TEAMCITY_VERSION`). If none of these variables are set, it assumes it is running on a developer machine.
+If it mistakes a CI environment for a developer machine, add a `CI` environment variable (with any value) to the workflow, or [use `--no-token`](#how-to-use---no-token) to disable configuring the npm token.
+:::
+
+## Configuring NPM Token in CI
+
+In CI environments such as Teamcity and Github, use the `ST_NPM_READONLY_TOKEN` organization secret to grant access to private ServiceTitan packages. You can do this in two ways:
+
+### Option 1: Inject into .npmrc (Recommended)
+
+The recommended method is to use `npm config set --location=project` to manually inject the organization secret into the project's `.npmrc`. For example,
+
+<Tabs
+defaultValue="github"
+values={[{ label: "Github Action", value: "github"}, {label: "Dockerfile", value: "docker"}]}>
+
+<TabItem value="github">
+
+```yml
+- run: npm config set --location=project "//registry.npmjs.org/:_authToken"="${{ secrets.ST_NPM_READONLY_TOKEN }}"
+- run: npm run build
+```
+
+Alternatively, in Github actions using `action/setup-node`, you can use `registry-url` and `env.NODE_AUTH_TOKEN` to have it configure the project level `.npmrc`. For example,
+
+```yml
+- uses: actions/setup-node@v4
+  registry-url: https://registry.npmjs.org
+  env:
+      NODE_AUTH_TOKEN: ${{ secrets.ST_NPM_READONLY_TOKEN }}
+```
+
+</TabItem>
+<TabItem value="docker">
+
+```dockerfile
+ARG NPM_READONLY_TOKEN
+
+RUN npm config set --location=project "//registry.npmjs.org/:_authToken=$NPM_READONLY_TOKEN"
+RUN npm run build
+```
+
+</TabItem>
+</Tabs>
+
+### Option 2: Use environment variable
+
+:::caution
+Using an environment variable is not recommended because it requires [extra steps](#how-to-configure-with-legacy-startup) to rotate the token in projects using `startup` v31 or earlier.
+:::
+
+To use an environment variable to configure the npm token, modify `.npmrc` to get the token from an environment variable,
+
+```npmrc title=".npmrc"
+//registry.npmjs.org/:_authToken=${NPM_READONLY_TOKEN}
+```
+
+Then, in the CI action, set that environment variable to the organization secret. For example,
+
+<Tabs
+defaultValue="github"
+values={[{ label: "Github Action", value: "github"}, {label: "Dockerfile", value: "docker"}]}>
+
+<TabItem value="github">
+
+```yml
+- run: npm run build
+  env:
+      NPM_READONLY_TOKEN: ${{ secrets.ST_NPM_READONLY_TOKEN }}
+```
+
+</TabItem>
+<TabItem value="docker">
+
+```dockerfile
+ARG NPM_READONLY_TOKEN
+
+ENV NPM_READONLY_TOKEN=${NPM_READONLY_TOKEN}
+
+RUN npm run build
+```
+
+</TabItem></Tabs>
+
+## How to Configure Development Environment When Not Using Startup v32 or Later {#how-to-configure-with-legacy-startup}
+
+:::note
+These instructions are only for projects using [Option 2](#option-2-use-environment-variable) with `startup` v31 or earlier (or that are not using `startup` at all);
+`startup` v32 automatically detects and provides environment variables to `npm install`.
+:::
+
+If your project is [using an environment variable](#option-2-use-environment-variable), and it isn't using `startup` v32 or later, then developers must also defined the same environment variable manually. And they must repeat these steps each time the token is rotated,
+
+1. Run `npx --yes @servicetitan/startup@latest install` to add the token to your per-user configuration.
+2. Run `npm config get userconfig` to get the location of your per-user configuration file.
+3. Find the token in the configuration file, on the line that starts `//registry.npmjs.org/:_authToken=`
+4. Create a local environment variable with the token. Use the same variable name as in project's `.npmrc`.
+
+:::tip
+On MacOS you can accomplish steps 2 and 3 with this single command:
+
+```sh
+grep registry.npmjs.org < $(npm config get userconfig)
+```
+
+:::
+
+## How to Use --no-token
+
+If startup mistakes your CI environment for a development machine and it isn't practical to add a `CI` environment variable to the workflow, use `--no-token` to instruct `startup install` not to attempt to configure the npm token.
+
+Create a `build:ci` script and accompanying pre script that runs `bootstrap` with `-- --no-token`:
+
+```json title="package.json"
+    "scripts": {
+        "prebuild:ci": "npm run bootstrap -- --no-token",
+        "build:ci": "startup build"
+    },
+```
+
+Then, call `build:ci` instead of `build` in the CI workflow:
+
+```sh
+npm run build:ci
+```
+
+:::note
+This assumes you're using this recommended `bootstrap` script:
+
+```json
+    "scripts": {
+        "bootstrap": "npx --yes @servicetitan/startup install",
+    }
+```
+
+:::

package/docs/startup/review.mdx

@@ -192,6 +192,32 @@ npm pkg set "main"="dist/index.js" -w packages/lib
 
 ---
 
+### require-all-react-dependencies
+
+Ensures that any package which depends on either `react` or `react-dom` explicitly lists both as dependencies.
+React and ReactDOM are tightly coupled and should always be paired together to avoid runtime issues.
+
+#### ✅ Autofix
+
+This rule supports autofix.
+It adds the missing `react` or `react-dom` dependency, using the same version that is already present. For example, given:
+
+```json title="package.json"
+{
+    "dependencies": {
+        "react": "^18.3.1"
+    }
+}
+```
+
+It runs:
+
+```sh
+npm pkg set dependencies["react-dom"]="^18.3.1"
+```
+
+---
+
 ### require-explicit-side-effects
 
 Warns if a package is missing the `sideEffects` property in its `package.json`.
@@ -290,6 +316,22 @@ It sets the version of each dependency to the [highest](#highest-versions) of th
 
 ---
 
+### require-one-react-version
+
+Ensures the same version of `react` and `react-dom` is used across the workspace.
+
+These two packages are fundamentally designed to work together, with `react-dom` relying heavily on the internal structures and mechanisms exposed by `react`.
+
+While React 17 introduced features for gradual upgrades and potentially using multiple React versions in specific scenarios, maintaining synchronized versions of `react` and `react-dom` is the recommended and safest practice to ensure compatibility and avoid unforeseen issues.
+
+#### ✅ Autofix
+
+This rule supports autofix.
+It sets `react` and `react-dom` to the most common version in the repo.
+If multiple versions tie for the most common, it uses the [highest](#highest-versions) version among the top contenders.
+
+---
+
 ### require-one-uikit-version
 
 Ensures the same version of related `uikit` packages is installed across the workspace.

package/docs/startup/start.mdx

@@ -17,4 +17,4 @@ Runs package in the development mode. Applications will be hosted on sequential
 
 The `start` command executes the same steps as the `build` command, then watches for changes and automatically reruns each step as needed.
 
-See [Build Steps](/docs/frontend/uikit/startup/build#build-steps).
+See [Build Steps](./build#build-steps).

package/docs/startup/test.mdx

@@ -2,10 +2,204 @@
 title: test
 ---
 
-Runs all existing tests in all packages.
+Runs your project's tests.
 
-To run tests a subset of tests is possible to pass paths to specific directories or test files as positional parameters.
+- Supports both Jest and Vitest.
+- Automatically selects the test runner based on your workspace configuration or the `--runner` option.
+- Handles runner-specific arguments and passes them through to the underlying test tool.
+
+## Usage
+
+Run all tests with Jest (default):
+
+```sh
+npx startup test
+```
+
+Run all tests with Vitest:
+
+```sh
+npx startup test --runner vitest
+```
+
+:::tip
+Use the double-dash (--) separator to pass arguments to an `npm` script.
+This separator indicates that any arguments following it should be passed directly to the script being executed, rather than being interpreted by `npm` itself.
+For example, given the standard `startup test` script:
+
+```json
+{
+    "test": "npx startup test"
+}
+```
+
+Running,
+
+```sh
+npm run test -- --runner vitest
+```
+
+Executes,
+
+```sh
+npx startup test --runner vitest
+```
+
+:::
+
+## Running Specific Tests
+
+To run specific tests, pass their file names or paths as additional arguments.
+This works just like running Jest and Vitest directly, simply specify the file(s) you want to test:
+
+### Examples
+
+Run a specific test with Jest (default):
+
+```sh
+npx startup test app.test.tsx
+```
+
+Run a specific test with Vitest:
+
+```sh
+npx startup test --runner vitest app.test.tsx
+```
+
+## Using Jest
+
+The `startup test` command uses the Jest test runner by default.
+
+### Configuration
+
+The Jest runner provides a default, built-in configuration optimized for ServiceTitan workspaces.
+
+You can override the defaults by specifying [Jest options](https://jestjs.io/docs/configuration) in your workspace `package.json` under the `"cli.jest"` key (the `"cli.test"` key also works, for backward compatibility). You can also use a standard Jest config file (such as `jest.config.js`) to override defaults.
+
+Any options passed directly via the command line (e.g., `npx startup test --coverage`) take the highest precedence.
+
+:::caution
+If your project includes a standard Jest config file and also specifies Jest options in the workspace `package.json`, ensure that the configurations are mutually exclusive.
+To avoid confusing or unexpected behavior, do not specify the same setting in both locations.
+:::
+
+### Examples
+
+Use the workspace `package.json` to set up code that runs before each test file is executed:
+
+```json title="package.json"
+{
+    "cli": {
+        "jest": {
+            "setupFilesAfterEnv": ["<rootDir>/jest.setup.ts"]
+        }
+    }
+}
+```
+
+:::note
+For backward compatibility, you may also use the `ci.test` key:
+:::
+
+---
+
+Use `jest.config.js` to increase Jest's `testTimeout` on Windows:
+
+```js title="jest.config.js"
+module.exports = {
+    testTimeout: process.platform === 'win32' ? 60 * 1000 : undefined, // increase timeout on Windows
+};
+```
+
+---
+
+Use the command line to collect test coverage:
+
+```sh
+npx startup test --coverage
+```
+
+Use the command line to enable Jest's watch mode:
+
+```sh
+npx startup test --watch
+```
+
+## Using Vitest
+
+✨ New in **v31.6.0** ✨
+
+You can change the default test runner to `vitest` in your workspace's `package.json`:
+
+```json title="package.json"
+{
+    "cli": {
+        "testRunner": "vitest"
+    }
+}
+```
+
+Or override it per invocation with the `--runner` option.
+
+### Configuration
+
+The Vitest runner uses a layered configuration approach to provide sensible defaults while allowing full customization.
+
+- Uses the default, built-in configuration as a base.
+- Applies workspace overrides from `package.json`.
+- Applies overrides from your Vitest config file.
+- Applies command line options last.
+
+1. **Default Configuration:**  
+   The runner starts with a built-in default configuration optimized for ServiceTitan workspaces. This includes sensible coverage settings, the environment (`jsdom`), file exclusions, and more.
+
+2. **Workspace Configuration:**  
+   You can override defaults by specifying [Vitest options](https://vitest.dev/config) in your workspace `package.json` under the `"cli.vitest"` key.
+
+3. **Vitest Config File:**  
+   If your project includes a standard Vitest config file (such as `vitest.config.ts` or `vite.config.ts`), its settings will override both the defaults and workspace configuration.
+
+4. **Command Line Arguments:**  
+   Any options passed directly via the command line (e.g., `npx startup test --runner vitest --coverage`) take highest precedence and override all previous configuration layers.
+
+### Examples
+
+Use workspace `package.json` to make `vitest` APIs available [globally](https://vitest.dev/config/#globals) like Jest:
+
+```json title="package.json"
+{
+    "cli": {
+        "vitest": {
+            "globals": true
+        }
+    }
+}
+```
+
+---
+
+Use Vitest config file to disable watch mode:
+
+```ts title="vitest.config.mts"
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+    test: {
+        watch: false,
+    },
+});
+```
+
+---
+
+Use the command line to disable watch mode:
+
+```sh
+npx startup test --runner vitest --run
+```
+
+Use the command line to collect code coverage:
 
 ```sh
-npx startup test -- packages/desktop/app/modules/inventory/
+npx startup test --runner vitest --coverage
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@servicetitan/docs-uikit",
-    "version": "31.5.1",
+    "version": "32.0.0",
     "description": "",
     "repository": {
         "type": "git",
@@ -16,5 +16,5 @@
     "cli": {
         "webpack": false
     },
-    "gitHead": "8eb35a6e98b9e3cb3b18b452ce9ba76f278d0e61"
+    "gitHead": "af064114b3ec8c08a4b693a66c4062a52b03504c"
 }