@servicetitan/docs-uikit 32.1.0 → 32.2.0

package/docs/startup/startup.mdx

@@ -34,125 +34,14 @@ Updating build tooling is typically a daunting and time-consuming task. When new
 - [start](./start) run project in development mode
 - [test](./test) run tests
 
-## Package Setup
+## Configuration
 
-Because `startup` compiles and builds in separate steps, packages should export the compiled output instead of the TypeScript source files.
+Use the `cli` key in `package.json` to customize `startup` behavior. The following options apply to all commands. See the [commands](#commands) for command-specific options.
 
-For example, the Webpack documentation suggests a configuration that directs webpack to enter through `./src/index.ts` and load all `.ts` and `.tsx` files through `ts-loader`. However, because `startup` precompiles Typescript files, this is redundant and webpack should be configured to load the compiled Javascript.
-
-```json title="package.json"
-{
-    "exports": "./dist/index.js",
-    "main": "./dist/index.js",
-    "typings": "./dist/index.d.ts"
-}
-```
-
-And, [TypeScript project references](https://www.typescriptlang.org/docs/handbook/project-references.html) should be used to describe the dependencies between components.
-
-```json title="tsconfig.json"
-{
-    "references": [
-        { "path": "../component-a" },
-        { "path": "../component-b" },
-        { "path": "../component-c" }
-    ]
-}
-```
-
-## CSS Modules
-
-This project supports [CSS Modules](https://github.com/css-modules/css-modules) alongside regular stylesheets using the `[name].module.{css,less,scss}` file naming convention. It allows the scoping of CSS by automatically creating a unique class name.
-
-## SVG Transformation
-
-:::caution
-Type definitions are provided for the various ways of importing SVGs via the base tsconfig's
-`"files"` property within `startup`. If you override the `"files"` property
-within your tsconfig, you may lose access to these type definitions, and will need to add them
-manually.
-:::
-
-By default, SVGs are loaded as assets. Depending on the file size, the asset is converted to a base64 URI string, or emitted as separate file.
-
-```tsx
-import MySVG from './my.svg';
-...
-<img src={MySVG} />
-```
-
-When importing SVGs from Anvil 2 (`@servicetitan/anvil2`), [SVGR](https://react-svgr.com/) is used to transform SVGs into React components.
-
-```tsx
-import CheckIcon from '@servicetitan/anvil2/assets/icons/material/round/check.svg';
-...
-<CheckIcon />
-```
-
-In order to use SVGR with SVGs outside of Anvil 2, you can import them as components by passing the `?component` query to the important statement. For example:
-
-```tsx
-import CheckIcon from './assets/check.svg?component';
-...
-<CheckIcon />
-```
-
-If you'd like to use SVGs imported from Anvil 2 as assets, you can pass the `?asset` query to the import statement. For example:
-
-```tsx
-import CheckIcon from '@servicetitan/anvil2/assets/icons/material/round/check.svg?asset';
-...
-<img src={CheckIcon} />
-```
-
-## Configuration Customization
-
-The zero-configuration approach is a good fit for most use cases, but sometimes applications need to extend or override configurations.
-Use the `cli` node in `package.json` to customize `startup` behavior.
-
-### Project-wide settings
-
-#### Jest
-
-Use `cli.test` to set or override Jest options. E.g.,
-
-```json title="package.json"
-{
-    "cli": {
-        "test": {
-            // Jest options (https://jestjs.io/docs/next/configuration)
-        }
-    }
-}
-```
-
-#### Linting
-
-Use `cli.lint` to set or override `ESLint` and `Stylelint` options. E.g,
-
-```json title="package.json"
-{
-    "cli": {
-        "lint": {
-            "eslint": {
-                // ESLint options (https://eslint.org/docs/user-guide/configuring)
-            },
-            "stylelint": {
-                // Stylelint options (https://stylelint.io/user-guide/configure)
-            }
-        }
-    }
-}
-```
-
-#### NODE_OPTIONS
+### NODE_OPTIONS
 
 Use `cli.NODE_OPTIONS` or `cli.*.NODE_OPTIONS` to set or override Node options for some or all commands. E.g.,
 
-:::note
-`startup` automatically runs memory intensive commands (e.g., `build`, `start`, `lint` and `test`) with `--max_old_space_size=8192` by default.
-:::
-
 ```json title="package.json"
 {
     "cli": {
@@ -171,265 +60,6 @@ Use `cli.NODE_OPTIONS` or `cli.*.NODE_OPTIONS` to set or override Node options f
 }
 ```
 
-### Package-specific settings
-
-#### Type checking
-
-Use package-specific `tsconfig.json` and `tsconfig.build.json` files to set or override type checking options. E.g.,
-
-```json title="tsconfig.json"
-{
-    "extends": "@servicetitan/startup/tsconfig/base",
-    "compilerOptions": {
-        "outDir": "dist",
-        "rootDir": "src",
-        ... // Other type checking options (https://www.typescriptlang.org/tsconfig/)
-    },
-    "include": ["src/**/*"]
-}
-```
-
-`tsconfig.build.json` takes precedence over `tsconfig.json`. Use `tsconfig.build.json` that extends from `tsconfig.json` to exclude tests, stories, and mocks from type checking during development. E.g.,
-
-:::caution
-If your `tsconfig.json` configures project references they must be duplicated in `tsconfig.build.json`.
-
-See [references are not inherited in tsconfig.json](https://github.com/microsoft/TypeScript/issues/27098).
+:::tip
+`Startup` automatically uses `--max_old_space_size` to increase available memory for memory intensive commands like `build`, `start`, `lint` and `test`.
 :::
-
-```json title="tsconfig.build.json"
-{
-    "extends": "./tsconfig.json",
-    "exclude": ["**/__tests__/*", "**/*.test.*", "**/__mocks__/*", "**/*.stories.*"],
-    "references": [
-        { "path": "../feature-a" },
-        { "path": "../feature-b" },
-        { "path": "../feature-c" }
-    ]
-}
-```
-
-#### TypeScript compilation (SWC)
-
-Use `cli.swc-compile-package` to set or override SWC options. E.g.,
-
-:::note
-SWC uses a subset of the project-specific `tsconfig.json` file to map SWC options. See [cliOptions](https://github.com/search?q=repo%3Aservicetitan%2Fuikit+%22cliOptions%3A%22+-path%3A**%2F*.test.ts&type=code) and [swcOptions](https://github.com/search?q=repo%3Aservicetitan%2Fuikit+%22swcOptions%3A%22+-path%3A**%2F*.test.ts&type=code) for mapping details.
-:::
-
-```json title="package.json"
-{
-    "cli": {
-        "swc-compile-package": {
-            "cliOptions": {
-                // CLI options (https://swc.rs/docs/usage/cli)
-            },
-            "swcOptions": {
-                // Compilation options (https://swc.rs/docs/configuration/compilation)
-                // Module options (https://swc.rs/docs/configuration/modules)
-            }
-        }
-    }
-}
-```
-
-#### TypeScript compilation (TSC)
-
-:::caution
-Compilation via TSC is deprecated.
-:::
-
-Use project-specific `tsconfig.json` and `tsconfig.build.json` files to set or override compiler options. See [Type checking](/docs/startup/#type-checking) for more information.
-
-#### Microfrontends (MFEs)
-
-Set `cli.web-component` to `true` to create the support files and `light` and `full` bundles for MFE applications. E.g.,
-
-```json title="package.json"
-{
-    "cli": {
-        "web-component": true
-    }
-}
-```
-
-Or you can set an object with detailed configs:
-
-```json title="package.json"
-{
-    "cli": {
-        "web-component": {
-            "branches": {
-                "qa": { "publishTag": "qa" }
-            }
-        }
-    }
-}
-```
-
-Or you can use relative path to a file that exports an object with detailed configs (useful to share configs between multiple MFEs in repo):
-
-```json title="package.json"
-{
-    "cli": {
-        "web-component": "../../config/web-component.js"
-    }
-}
-```
-
-###### Web component config options
-
-- `cli.web-component.branches` - Set git branch specific configs, used for publishing. See [Branch configs](./mfe-publish#branch-configs).
-- `cli.web-component.legacyRoot` - Set to opt-out of automatic batching. See [Opting-out of automatic batching](/docs/frontend/react-18#opting-out-of-automatic-batching).
-
-See [MFE configuration](/docs/frontend/micro-frontends/#mfe-configuration) for detailed instructions on configuring MFE applications.
-
-###### Headless bundle
-
-If a file named `headless.ts` is present in the source folder of an MFE package, `startup` automatically generates a headless bundle alongside the `light` and `full` bundles. See [web-components documentation](../web-components/headless-loader) for information on the headless bundle.
-
-#### Webpack
-
-Use `cli.webpack` to set or override Webpack options.
-
-##### Non-application packages
-
-Set `cli.webpack` to `false` to disable Webpack bundling for non-application NPM packages, such as component and utility libraries. E.g.,
-
-```json title="package.json"
-{
-    "cli": {
-        "webpack": false
-    }
-}
-```
-
-##### Minification
-
-By default `startup` configures webpack to minify production bundles conservatively,
-so that projects gain the benefits of reduced bundle sizes while retaining the highest
-fidelity for source map debugging.
-
-Set `cli.webpack.minify.js` or `cli.webpack.minify.css` to `false` to prevent webpack from minifying JS or CSS bundles.
-
-`startup` uses [TerserWebpackPlugin](https://webpack.js.org/plugins/terser-webpack-plugin) to minify JS bundles
-and uses [CssMinimizerWebpackPlugin](https://webpack.js.org/plugins/css-minimizer-webpack-plugin)
-to minify CSS bundles.
-
-To override the default Terser options set `cli.webpack.minify.js` to an object containing
-[`terserOptions`](https://webpack.js.org/plugins/terser-webpack-plugin/#terseroptions).
-To override the default CssMinimizerWebpackPlugin options, set `cli.webpack.minify.css` to an object containing
-[CssMinimizerWebpackPlugin options](https://webpack.js.org/plugins/css-minimizer-webpack-plugin/#options).
-E.g.,
-
-```json title="package.json"
-{
-    "cli": {
-        "webpack": {
-            "minify": {
-                "js": {
-                    // terser-webpack-plugin terserOptions
-                },
-                "css": {
-                    // css-minimizer-webpack-plugin options
-                }
-            }
-        }
-    }
-}
-```
-
-##### Application Port
-
-Use `cli.webpack.port` to set the port that `webpack-dev-server` uses for the application. E.g.,
-
-```json title="package.json"
-{
-    "cli": {
-        "webpack": {
-            "port": 8888
-        }
-    }
-}
-```
-
-##### webpack-dev-server
-
-Use `cli.webpack.devServer` to set or override `webpack-dev-server` options. E.g.,
-
-```json title="package.json"
-{
-    "cli": {
-        "webpack": {
-            "devServer": {
-                // webpack-dev-server options (https://webpack.js.org/configuration/dev-server/#devserver)
-            }
-        }
-    }
-}
-```
-
-`webpack.devServer` can also be set to `false` in order to disable `webpack-dev-server` altogether.
-
-#### Webpack Configuration
-
-If you need to add additional rules or change the build output path or make any other customization of the Webpack configuration, you should create `webpack.{env}.config.js` files in the package's root folder. These files should call `createWebpackConfig` with the required configuration.
-
-##### createWebpackConfig
-
-Accepts an object with two fields: `configuration` and `plugins` with configuration overrides for Webpack and its plugins, and returns the Webpack configuration for the provided `configuration.mode` with applied overrides.
-Currently `plugins` only supports `HtmlWebpackPlugin` and `MiniCssExtractPlugin`, and `MiniCssExtractPlugin` can only be overridden in production builds.
-
-```js title="webpack.dev.config.js"
-const path = require('path');
-
-const { createWebpackConfig } = require('@servicetitan/startup');
-
-module.exports = createWebpackConfig({
-    configuration: {
-        mode: 'development',
-        output: { path: path.resolve(__dirname, '../../wwwroot') },
-    },
-});
-```
-
-```js title="webpack.prod.config.js"
-const path = require('path');
-
-const { createWebpackConfig } = require('@servicetitan/startup');
-
-module.exports = createWebpackConfig({
-    configuration: {
-        mode: 'production',
-        output: { path: path.resolve(__dirname, '../../wwwroot') },
-    },
-});
-```
-
-##### MFE webpack config
-
-Since `v22.7.0` providing custom webpack configuration for MFEs is also supported. However, there is a caveat. You can't use the `createWebpackConfig` to create the configuration as MFEs exist in two variants: a full build (includes all dependencies of MFE) and a light build (has shared dependencies with the host app and does not bundle these deps). See the [discussion here](https://github.com/servicetitan/uikit/pull/1721#discussion_r1183007790) for more info. Below are examples of MFE webpack configs. These objects are then internally passed to `createWebpackConfig` (so the same limitation applies meaning only a few `plugins` can be specified in the config file, see the previous section on `createWebpackConfig`).
-
-```js title="webpack.dev.config.js"
-const path = require('path');
-
-module.exports = {
-    configuration: {
-        mode: 'development',
-        output: { path: path.resolve(__dirname, '../../wwwroot') },
-    },
-    plugins: [...]
-};
-```
-
-```js title="webpack.prod.config.js"
-const path = require('path');
-
-module.exports = {
-    configuration: {
-        mode: 'production',
-        output: { path: path.resolve(__dirname, '../../wwwroot') },
-    },
-    plugins: [...]
-};
-```

package/docs/startup/test/jest.mdx

@@ -0,0 +1,114 @@
+---
+title: Jest
+---
+
+`Startup test` uses the Jest by default, with a built-in configuration optimized for ServiceTitan workspaces.
+
+## Configuration
+
+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). For example,
+
+```json title="package.json"
+{
+    "cli": {
+        "jest": {
+            // Jest options (https://jestjs.io/docs/next/configuration)
+        }
+    }
+}
+```
+
+You can also use a standard Jest config file (such as `jest.config.js`) or pass options directly via the command line (e.g., `npx startup test --coverage`).
+
+## Examples
+
+### Package.json
+
+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:
+:::
+
+### Config file
+
+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
+};
+```
+
+:::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.
+:::
+
+#### Overriding defaults
+
+✨ New in **v32.2.0** ✨
+
+Because Jest gives `startup`'s built-in defaults higher precedence than its config files, `startup` allows you to selectively omit built-in defaults so that they don't interfere.
+
+Set `cli.jest.omitDefault` to a list of options to omit from `startup`s built-in configuration.
+
+For example, to configure `transformIgnorePatterns` in `jest.config.js` omit it from `startup`'s defaults,
+
+```json title="package.json"
+{
+    "cli": {
+        "jest": {
+            "omitDefault": ["transformIgnorePatterns"]
+        }
+    }
+}
+```
+
+And export it from the Jest config,
+
+```js title="jest.config.js"
+const esmPackages = [
+    '@servicetitan',
+    '@react-hook',
+    'nanoid',
+    'axios',
+    'cpx2',
+    'p-map',
+    'terminal-link',
+    'ansi-escapes',
+    'environment',
+    'until-async',
+    'supports-hyperlinks',
+    'supports-color',
+    'has-flag',
+];
+
+module.exports = {
+    transformIgnorePatterns: [`node_modules/(?!(${esmPackages.join('|')})/)`],
+};
+```
+
+### Command line
+
+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
+```

package/docs/startup/test/test.mdx

@@ -0,0 +1,72 @@
+---
+title: test
+---
+
+Runs your project's tests.
+
+- 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
+```
+
+## Configuration
+
+- [Jest](./jest)
+- [Vitest](./vitest)

package/docs/startup/test/vitest.mdx

@@ -0,0 +1,117 @@
+---
+title: Vitest
+---
+
+✨ New in **v31.6.0** ✨
+
+You can change the default test runner from `jest` to `vitest` in your workspace's `package.json`:
+
+```json title="package.json"
+{
+    "cli": {
+        "testRunner": "vitest"
+    }
+}
+```
+
+Or, you can 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.
+- Merges workspace settings from `package.json`.
+- Merges settings from your Vitest config file.
+- Merges 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 customize the configuration 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 merged with 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 over previous configuration layers.
+
+## Examples
+
+### Package.json
+
+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
+        }
+    }
+}
+```
+
+### Config file
+
+Use `vitest.config.mts` to disable watch mode:
+
+```ts title="vitest.config.mts"
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+    test: {
+        watch: false,
+    },
+});
+```
+
+#### Overriding defaults
+
+✨ New in **v32.2.0** ✨
+
+Because Vitest merges `startup`'s built-in defaults with its config files,
+`startup` allows you to selectively omit built-in defaults so that they don't interfere.
+
+Set `cli.vitest.omitDefault` to a list of options to omit from `startup`'s built-in configuration.
+
+For example, to completely customize `coverage.include`, omit it from `startup`s defaults:
+
+```json title="package.json"
+{
+    "cli": {
+        "vitest": {
+            "omitDefault": ["coverage.include"]
+        }
+    }
+}
+```
+
+And export it from the Vitest config,
+
+```js title="vitest.config.mts"
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+    test: {
+        coverage: {
+            include: ['apps/*/src/**', 'libraries/*/src/**'],
+        },
+    },
+});
+```
+
+### Command line
+
+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 --runner vitest --coverage
+```