@servicetitan/docs-uikit 32.1.0 → 32.3.0

package/docs/startup/build.mdx

@@ -6,14 +6,14 @@ Build packages for production to the `dist/bundle` folders. It bundles them in p
 
 ## Options
 
-| Option             | Description                                                                                                                                                                                 |
-| :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `--scope <glob>`   | Include only packages with names matching the given glob.                                                                                                                                   |
-| `--ignore <glob>`  | Exclude packages with names matching the given glob.                                                                                                                                        |
-| `--cdn-path <url>` | Specify the base path for all the assets within the application.                                                                                                                            |
-| `--stat`           | Generate bundle report with [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer). Starting `v22.3.0` works for [MFEs](/docs/frontend/micro-frontends) too. |
-| `--code-coverage`  | Add [instrumentation](https://github.com/JS-DevTools/coverage-istanbul-loader) to bundled code in order to collect code coverage                                                            |
-| `--use-tsc`        | Use TSC for TypeScript compilation                                                                                                                                                          |
+| Option             | Description                                                                                                                                                                    |
+| :----------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--scope <glob>`   | Include only packages with names matching the given glob.                                                                                                                      |
+| `--ignore <glob>`  | Exclude packages with names matching the given glob.                                                                                                                           |
+| `--cdn-path <url>` | Specify the base path for all the assets within the application.                                                                                                               |
+| `--stat`           | Generate bundle report with [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer). Starting `v22.3.0` works for [MFEs](../microfrontends) too. |
+| `--code-coverage`  | Add [instrumentation](https://github.com/JS-DevTools/coverage-istanbul-loader) to bundled code in order to collect code coverage                                               |
+| `--use-tsc`        | Use TSC for TypeScript compilation                                                                                                                                             |
 
 ## Build Steps
 
@@ -28,3 +28,276 @@ The `build` command executes these steps:
 :::note
 `startup` doesn't support dependencies between the Webpack bundles.
 :::
+
+## Package Setup
+
+Because `startup` compiles and builds in separate steps, packages must export compiled Javascript instead of the TypeScript source files. E.g.,
+
+```json title="package.json"
+{
+    "exports": "./dist/index.js",
+    "main": "./dist/index.js",
+    "typings": "./dist/index.d.ts"
+}
+```
+
+And, to ensure packages are compiled in the correct order, [TypeScript project references](https://www.typescriptlang.org/docs/handbook/project-references.html) must accurately describe the dependencies between packages. E.g.,
+
+```json title="tsconfig.json"
+{
+    "references": [
+        { "path": "../component-a" },
+        { "path": "../component-b" },
+        { "path": "../component-c" }
+    ]
+}
+```
+
+:::note
+The Webpack documentation suggests using a configuration that enters through `./src/index.ts`, and using `ts-loader` to process `.ts` and `.tsx` files. However, because `startup` precompiles Typescript, this is redundant and webpack must be configured to load the compiled Javascript.
+:::
+
+## CSS Modules
+
+`Startup` supports [CSS Modules](https://github.com/css-modules/css-modules) alongside regular stylesheets using the `[name].module.{css,less,scss}` file naming convention. CSS Modules provide locally scoped class names that prevent global CSS collisions, making styles more predictable and easier to refactor.
+
+## SVG Transformation
+
+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. E.g.,
+
+```tsx
+import MySVG from './my.svg';
+
+function MyImage() {
+    return <img src={MySVG} />;
+}
+```
+
+### Importing SVGs as React components
+
+By default `startup` imports SVGs from `@servicetitan/anvil2` as React components. E.g.,
+
+```tsx
+import { Button } from '@servicetitan/anvil2';
+import CheckIcon from '@servicetitan/anvil2/assets/icons/material/round/check.svg';
+
+export function CheckButton() {
+    return <Button icon={CheckIcon} />;
+}
+```
+
+To import SVGs from other sources as React components, append `?component` to the import statement. E.g.,
+
+```tsx
+import { Button } from '@servicetitan/anvil2';
+import CheckIcon from './assets/check.svg?component';
+
+export function CheckButton() {
+    return <Button icon={CheckIcon} />;
+}
+```
+
+### Importing Anvil 2 SVGs as assets
+
+By default `startup` imports SVGs from `@servicetitan/anvil2` as React components.
+To import an Anvil 2 SVG as an asset, append `?asset` to the import statement. E.g.,
+
+```tsx
+import CheckIcon from '@servicetitan/anvil2/assets/icons/material/round/check.svg?asset';
+
+function CheckImage() {
+    return <img src={CheckIcon} />;
+}
+```
+
+## Configuration
+
+### Library packages
+
+Set `cli.webpack` to `false` to disable Webpack for non-application packages, such as component and utility libraries.
+
+```json title="package.json"
+{
+    "cli": {
+        "webpack": false
+    }
+}
+```
+
+### 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/**/*"]
+}
+```
+
+Use `tsconfig.build.json` that extends from `tsconfig.json` to exclude tests, stories, and mocks from type checking. E.g.,
+
+```json title="tsconfig.build.json"
+{
+    "extends": "./tsconfig.json",
+    "exclude": ["**/__tests__/*", "**/*.test.*", "**/__mocks__/*", "**/*.stories.*"],
+    "references": [
+        { "path": "../feature-a" },
+        { "path": "../feature-b" },
+        { "path": "../feature-c" }
+    ]
+}
+```
+
+:::caution
+Project references must be duplicated in `tsconfig.build.json` because [references are not inherited](https://github.com/microsoft/TypeScript/issues/27098).
+:::
+
+### TypeScript compilation (SWC)
+
+:::info
+`Startup` only maps a subset of TypeScript settings from `tsconfig.json` to 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 the details.
+:::
+
+Use `cli.swc-compile-package` to set or override SWC options. E.g.,
+
+```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 package-specific `tsconfig.json` and `tsconfig.build.json` files to set or override compiler options. See [Type checking](#type-checking) for more information.
+
+### Minimization
+
+By default `startup` configures webpack to minimize production bundles conservatively,
+so that projects gain the benefits of reduced bundle sizes while retaining the highest
+fidelity for source map debugging.
+It uses [TerserWebpackPlugin](https://webpack.js.org/plugins/terser-webpack-plugin) to minimize JS bundles
+and [CssMinimizerWebpackPlugin](https://webpack.js.org/plugins/css-minimizer-webpack-plugin)
+to minimize CSS bundles.
+
+- To turn off minimizing, set `cli.webpack.minify.js` or `cli.webpack.minify.css`, or both, to `false`.
+- 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).
+
+For example,
+
+```json title="package.json"
+{
+    "cli": {
+        "webpack": {
+            "minify": {
+                "js": {
+                    // terser-webpack-plugin terserOptions
+                    // https://webpack.js.org/plugins/terser-webpack-plugin/#terseroptions
+                },
+                "css": {
+                    // css-minimizer-webpack-plugin options
+                    // https://webpack.js.org/plugins/css-minimizer-webpack-plugin/#options
+                }
+            }
+        }
+    }
+}
+```
+
+### Webpack
+
+To further customize Webpack settings, create files named `webpack.*.config.js` in the package's root directory (the directory with its `package.json`).
+
+Use `webpack.dev.config.js` to customize development builds and use `webpack.prod.config.js` to customize production builds. In the config file,
+
+- Import `createWebpackConfig` from `@servicetitan/startup`.
+- Call it with the custom Webpack options.
+- Return the result as the default export.
+
+For example, to customize the Webpack's **output** path,
+
+```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') },
+    },
+});
+```
+
+:::caution
+For MFEs the approach is slightly different, see [Customizing Webpack for MFEs](#customizing-webpack-for-mfes)
+:::
+
+#### createWebpackConfig
+
+`createWebpackConfig` takes an object with two fields, `configuration` and `plugins`.
+
+| Field           | Description                                                                                                                                                                                        |
+| :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `configuration` | Merged with the defaults to produce the final webpack configuration. For production builds, **configuration.mode** must be set to "production". For development builds, set it to "development".   |
+| `plugins`       | `HtmlWebpackPlugin` and `MiniCssExtractPlugin` subkeys are merged with the default configurations for the corresponding plugins. (Note, `MiniCssExtractPlugin` only applies to production builds.) |
+
+For example,
+
+```js title="webpack.prod.config.js"
+const { createWebpackConfig } = require('@servicetitan/startup');
+
+module.exports = createWebpackConfig({
+    configuration: {
+        mode: 'production',
+    },
+    plugins: {
+        HtmlWebpackPlugin: {
+            favicon: './favicon.ico',
+            title: 'Enterprise Hub',
+        },
+    },
+});
+```
+
+:::caution
+Remember, you must set `configuration.mode` to "production" in `webpack.prod.config.js`.
+:::
+
+#### Customizing Webpack for MFEs
+
+Because `startup` runs Webpack multiple times to create MFEs bundles, a slightly different approach is required for MFEs.
+Don't call `createWebpackConfig` and just return an object with the same `configuration` and `plugins` fields described [above](#createwebpackconfig).
+E.g.,
+
+```js title="webpack.dev.config.js"
+const path = require('path');
+
+module.exports = {
+    configuration: {
+        mode: 'development',
+        output: { path: path.resolve(__dirname, '../../wwwroot') },
+    },
+};
+```

package/docs/startup/install.mdx

@@ -17,14 +17,24 @@ See [package.json in the example project](https://github.com/search?q=repo%3Aser
 
 ## Options
 
-| Option       | Description                                   |
-| :----------- | :-------------------------------------------- |
-| `--no-token` | Disable configuring npm authentication token. |
+| Option       | Description                                                              |
+| :----------- | :----------------------------------------------------------------------- |
+| `--no-token` | Only install dependencies. Don't configure the npm authentication token. |
+| `--token`    | Only configure the npm authentication token. Don't install dependencies. |
 
 ## 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.
 
+:::tip
+If your project is using `startup` v31 or earlier, or isn't using `startup` at all, run this command to manually configure the npm authentication token.
+
+```
+npx --yes @servicetitan/startup@latest install --token
+```
+
+:::
+
 :::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.
@@ -119,7 +129,7 @@ These instructions are only for projects using [Option 2](#option-2-use-environm
 
 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.
+1. Run `npx --yes @servicetitan/startup@latest install --token` 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`.

package/docs/startup/lint.mdx

@@ -24,3 +24,26 @@ npx startup lint -- packages/desktop/app/modules/{lead,inventory}/
 | `--scope <glob>`  | Include only packages with names matching the given glob. |
 | `--ignore <glob>` | Exclude packages with names matching the given glob.      |
 | `--fix`           | Fix linting issues.                                       |
+
+## Configuration
+
+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)
+            }
+        }
+    }
+}
+```
+
+:::caution
+Because `lint` is a global command that runs from the workspace root, `ESLint` and `Stylelint` configurations must be in the workspace's root `package.json`.
+:::

package/docs/startup/mfe-list.mdx

@@ -0,0 +1,73 @@
+---
+title: mfe-list
+---
+
+Lists published MFE packages.
+
+Use `mfe-list` to see what MFE versions were published and when.
+
+```sh
+npx startup mfe-list
+```
+
+It outputs, for each MFE in the current workspace,
+
+- The MFE's name, current version, and total number of versions
+- A table listing the 20 most recently published versions, with the following columns:
+    - **Version** : the published version
+    - **Tag** : assigned tag (if any)
+    - **When** : when the version was published, relative to the current time
+
+For example,
+
+```
+@servicetitan/examples | version: 0.0.0-far1369uploadsourcemaps.8e4f1ca0 | versions: 20
+┌────────────────────────────────────────┬─────────┬───────────────┐
+│ Version                                │ Tag     │ When          │
+├────────────────────────────────────────┼─────────┼───────────────┤
+│ 0.0.0-far1369uploadsourcemaps.8e4f1ca0 │ latest  │ 2 months ago  │
+├────────────────────────────────────────┼─────────┼───────────────┤
+│ 0.0.0-test.7cf27f80                    │         │ 3 months ago  │
+├────────────────────────────────────────┼─────────┼───────────────┤
+│ 0.0.0-test.2c98b704                    │         │ 3 months ago  │
+
+~                                                                  ~
+~                                                                  ~
+├────────────────────────────────────────┼─────────┼───────────────┤
+│ 0.0.3                                  │         │ 4 years ago   │
+├────────────────────────────────────────┼─────────┼───────────────┤
+│ 1.2.4                                  │         │ 4 years ago   │
+└────────────────────────────────────────┴─────────┴───────────────┘
+```
+
+## Options
+
+| Option            | Description                                                         |
+| :---------------- | :------------------------------------------------------------------ |
+| `--all`           | List all published versions.                                        |
+| `--ignore <glob>` | Exclude MFEs with names matching the given glob pattern.            |
+| `--limit <count>` | List the last `<count>` published versions. Ignores `<count> <= 0`. |
+| `--tagged`        | List only tagged versions.                                          |
+
+## Listing specific MFEs
+
+To list specific MFEs, pass their package names on the command line. For example, to list all tagged versions of `@servicetitan/dispatch-center` run,
+
+```
+npx startup mfe-list @servicetitan/dispatch-center --tagged
+```
+
+:::tip
+Use this syntax to list any MFE, not just the ones in the project workspace.
+:::
+
+## Authorization
+
+If the machine is not authorized to access [Verdaccio](/docs/frontend/verdaccio-unpkg/#verdaccio), `startup` prompts you to authorize it. E.g.,
+
+```sh
+$ npx startup mfe-list
+This machine is not authorized to access https://verdaccio.servicetitan.com. Authorize? [Y/n]
+```
+
+Enter `y` to confirm, or `n` to cancel. If you confirm, `startup` runs [verdaccio-okta-oauth](/docs/frontend/verdaccio-unpkg/#authorzation) then proceeds with the command.

package/docs/startup/mfe-publish.mdx

@@ -6,18 +6,22 @@ This is an umbrella command for both publishing and unpublishing (cleaning up) M
 
 ## Publishing options
 
-| Option                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| :---------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--dry`                                         | Log what the command would do without actually publishing anything.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `--branch <string>`                             | Optional branch name. The current branch name is used if no value is specified. The branch name is used in constructing the build version in case `--build` is not specified.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `--build <glob>`                                | Optional build version that normally should not be specified. Defaults to `<branch_name>.<commit_hash>`. For example, if git commit `bdac90f5` is published from branch `next`, the build version is`next.bdac90f5`, and the full version is `0.0.0-next.bdac90f5`. This ensures each release has a unique version with no collisions.                                                                                                                                                                                                                                                                                           |
-| `--force`                                       | Forces publishing the package when no configuration was found for the specified branch (`--branch` or current branch).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `--upload-sourcemaps`, `--no-upload-sourcemaps` | Whether or not to [upload sourcemaps](#sourcemaps) to Datadog. Defaults to uploading sourcemaps.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `--tag <string>`                                | The [tag](https://docs.npmjs.com/cli/v7/commands/npm-publish#tag) to assign to the published version. Defaults to the tag associated with the branch from the custom [branch config](#branch-configs) or, if there is no custom branch config, from the [default branch config](https://github.com/servicetitan/uikit/blob/master/packages/startup/src/utils/get-branch-configs.ts#L3). For example, by default a package published from the `master` branch is tagged `prod`. Becasue NPM v11 requires pre-release versions to have a tag, if there is no custom or default tag for the branch, the package is tagged "latest". |
+| Option                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| :---------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--dry`                                         | Log what the command would do without actually publishing anything.                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `--branch <string>`                             | Optional branch name. The current branch name is used if no value is specified. The branch name is used in constructing the build version in case `--build` is not specified.                                                                                                                                                                                                                                                                                                  |
+| `--build <glob>`                                | Optional build version that normally should not be specified. Defaults to `<branch_name>.<commit_hash>`. For example, if git commit `bdac90f5` is published from branch `next`, the build version is`next.bdac90f5`, and the full version is `0.0.0-next.bdac90f5`. This ensures each release has a unique version with no collisions.                                                                                                                                         |
+| `--force`                                       | Forces publishing the package when no configuration was found for the specified branch (`--branch` or current branch).                                                                                                                                                                                                                                                                                                                                                         |
+| `--upload-sourcemaps`, `--no-upload-sourcemaps` | Whether or not to [upload sourcemaps](#sourcemaps) to Datadog. Defaults to uploading sourcemaps.                                                                                                                                                                                                                                                                                                                                                                               |
+| `--tag <string>`                                | The [tag](https://docs.npmjs.com/cli/v7/commands/npm-publish#tag) to assign to the published version. Defaults to the tag associated with the branch from the custom [branch config](#branch-configs) or, if there is no custom branch config, from the [default branch config](https://github.com/servicetitan/uikit/blob/master/packages/startup/src/utils/get-branch-configs.ts#L3). For example, by default a package published from the `master` branch is tagged `prod`. |
+
+:::danger
+Do not use the `@latest` tag for production deployments because it could be assigned unintentionally. NPM v11 requires all pre-release versions to have a tag and, if you don't specify a tag and `mfe-publish` can't infer a tag from the branch name, the pre-release will be tagged "latest".
+:::
 
 ## Unpublishing options
 
-| Option             | Descripiton                                                                                                                                   |
+| Option             | Description                                                                                                                                   |
 | :----------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- |
 | `--clean`          | Instructs `mfe-publish` to remove old versions instead of publishing.                                                                         |
 | `--all`            | Remove old versions associated with all [recognized branches](#branch-configs). This overrides `--branch`.                                    |
@@ -27,20 +31,25 @@ This is an umbrella command for both publishing and unpublishing (cleaning up) M
 
 ## Branch configs
 
+✨ New in **v28.1.1** ✨
+
 By default `mfe-publish` only publishes from a few [recognized branches](https://github.com/servicetitan/uikit/blob/master/packages/startup/src/utils/get-branch-configs.ts#L3) and you must use `--force` to publish from others.
 
 To customize the recognized branches for an MFE set `cli.web-component.branches` in the MFE's package.json to an object that maps branch names to the associated tag. For example,
 
 ```json
+{
     "cli": {
         "web-component": {
             "branches": {
-                "qa": { "publishTag": "qa" },
-                "staging": { "publishTag": "staging" },
+                "develop": { "publishTag": "dev" },
+                "stage": { "publishTag": "stage" },
+                "next": { "publishTag": "next" },
                 "master": { "publishTag": "prod" }
             }
         }
     }
+}
 ```
 
 ### Properties
@@ -50,6 +59,29 @@ To customize the recognized branches for an MFE set `cli.web-component.branches`
 | `publishTag`       | `string`  | The tag to use when publishing from the branch.              |
 | `uploadSourcemaps` | `boolean` | Whether to upload sourcemaps to Datadog. Defaults to `true`. |
 
+### Sharing branch configurations
+
+When a repo contains multiple MFE that share the same branches, you can set `cli.web-component` to the relative path to a file that exports the common configuration object. For example,
+
+```json title="package.json"
+{
+    "cli": {
+        "web-component": "../../config/web-component.js"
+    }
+}
+```
+
+```js title="config/web-component.js"
+module.exports = {
+    branches: {
+        develop: { publishTag: 'dev' },
+        stage: { publishTag: 'stage' },
+        next: { publishTag: 'next' },
+        master: { publishTag: 'prod' },
+    },
+};
+```
+
 ## Sourcemaps
 
 ✨ New in **v31.5.0** ✨
@@ -71,3 +103,8 @@ If `DATADOG_API_KEY` is not provided `mfe-publish` fails with an error. In CI en
 :::tip
 Use `--no-upload-sourcemaps` to prevent `mfe-publish` from attempting to upload sourcemaps, for example, for pre-release versions. See [Publishing options](#publishing-options).
 :::
+
+## See Also
+
+- [Example `mfe-publish` workflow](https://github.com/servicetitan/frontend-example/blob/master/.github/workflows/mfe-publish.yml)
+- [Example `mfe-publish --clean` workflow](https://github.com/servicetitan/frontend-example/blob/master/.github/workflows/mfe-clean.yml)

package/docs/startup/start.mdx

@@ -2,7 +2,16 @@
 title: start
 ---
 
-Runs package in the development mode. Applications will be hosted on sequential free ports starting from 8080. Pages will automatically reload on changes to the code.
+Serves applications and [MFEs](../microfrontends) during development, watches source files, and automatically reloads pages on changes.
+
+:::tip
+To serve an application without `start`, [build](./build) it, then point any static http server to the output **bundle** directory, where the browser will find `index.html`. For example, to serve with [`http-server`](https://www.npmjs.com/package/http-server)
+
+```sh
+npx -yes http-server packages/application/dist/bundle
+```
+
+:::
 
 ## Options
 
@@ -18,3 +27,39 @@ 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](./build#build-steps).
+
+## Configuration
+
+### Port
+
+Use `cli.webpack.port` to select the port to use for a package. By default, packages are served from the first available port starting from 8080.
+
+```json title="package.json"
+{
+    "cli": {
+        "webpack": {
+            "port": 8888
+        }
+    }
+}
+```
+
+### DevServer
+
+Use `cli.webpack.devServer` to set or override `webpack-dev-server` options.
+
+```json title="package.json"
+{
+    "cli": {
+        "webpack": {
+            "devServer": {
+                // webpack-dev-server options (https://webpack.js.org/configuration/dev-server/#devserver)
+            }
+        }
+    }
+}
+```
+
+:::tip
+Set `cli.webpack.devServer` to `false` to disable `webpack-dev-server` altogether.
+:::