@servicetitan/docs-uikit 30.3.0 → 31.0.0

package/docs/startup.mdx

@@ -1,520 +0,0 @@
----
-title: Startup
----
-
-#### [CHANGELOG (@servicetitan/startup)](https://github.com/servicetitan/uikit/blob/master/packages/startup/CHANGELOG.md)
-
-[@servicetitan/startup](https://github.com/servicetitan/uikit/tree/master/packages/startup) is a command-line interface (CLI) to create multi-package Lerna projects with the support of TypeScript Project References and React. It offers a modern build setup with no configuration.
-
-## Why use this package?
-
-#### Less to learn
-
-No need to learn and configure build, lint, and testing environment. Quick reloads help to focus on development. When it's time to deploy bundles are optimized automatically.
-
-#### Dependencies encapsulation
-
-It's overwhelming how many development dependencies are required to work with the modern web application, with [@servicetitan/startup](https://github.com/servicetitan/uikit/tree/master/packages/startup) everything is already pre-included.
-
-#### Easy to maintain
-
-Updating build tooling is typically a daunting and time-consuming task. When new versions of [@servicetitan/startup](https://github.com/servicetitan/uikit/tree/master/packages/startup) are released, you just need to bump its version.
-
-## Commands
-
-:::caution
-Experimental flags don't follow semver. There might be breaking changes in minor versions of `@servicetitan/startup` when you opt-in to experimental flags.
-:::
-
-### convert-eslint-config
-
-Convert an ESLint v8 configuration to v9 format.
-
-```sh
-$ npx startup convert-eslint-config
-```
-
-Use this command when upgrading from ESLint v8 to v9, to convert a v8 `.eslintrc.json` to the equivalent `eslint.config.mjs`. See [Upgrading to ESLint v9.x](/docs/frontend/upgrading-to-eslint-v9) for guidance on upgrading to ESLint v9.
-
-The command takes no arguments. Simply run it from a directory with `.eslintrc.json` and it creates `eslint.config.mjs` in the same location.
-
-:::caution
-Comments are not copied from the source `.eslintrc.json` to the output file.
-If the source file contains important comments, copy them manually to the output file.
-:::
-
-### build
-
-Build packages for production to the `dist/bundle` folders. It bundles them in production mode and optimizes the build for the best performance. The builds are minified and the filenames include the hashes. Apps are ready to be deployed.
-
-#### Arguments
-
-- `--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.
-- `--esbuild` - Use [esbuild-loader](https://github.com/privatenumber/esbuild-loader) to process TypeScript files instead of ts-loader.
-- `--experimental-bundlers` - Use experimental build optimizations (alternative loaders and bundlers)
-- `--code-coverage` - Add [instrumentation](https://github.com/JS-DevTools/coverage-istanbul-loader) to bundled code in order to collect code coverage
-
-### init
-
-Generates initial project structure. This command should be run via `npx` in an empty folder.
-
-```sh
-$ npx -y @servicetitan/startup@latest init
-```
-
-### install
-
-Installs the package dependencies. This command should be run via `npx` before the build.
-
-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).
-
-### kendo-ui-license
-
-Activates KendoReact components by installing the license key. The license key is only installed if the project depends on `@progress/kendo` components. Otherwise, this command has no effect.
-
-**Note:** The [build](#build) command automatically detects when a project uses KendoRect components and runs this command.
-
-Use it to install the license key separately from a build, or to override the default license key.
-
-```sh
-$ npx startup kendo-ui-license
-```
-
-To install a different license, set the KENDO_UI_LICENSE environment variable to the key to use.
-
-```sh
-$ export KENDO_UI_LICENSE=<license-key>
-$ npx startup kendo-ui-license
-```
-
-### lint
-
-Runs ESLint and Stylelint for all codebase projects.
-
-To run ESLint and Stylelint on certain packages or subsystems it is possible to pass paths to specific directories as positional parameters.
-
-```sh
-$ npx startup lint -- packages/desktop/app/modules/inventory/
-```
-
-You can use multiple paths and your shell expressions which expand to directories.
-
-```sh
-$ npx startup lint -- packages/desktop/app/modules/lead/ packages/desktop/app/modules/inventory/
-$ npx startup lint -- packages/desktop/app/modules/{lead,inventory}/
-```
-
-#### Options
-
-- `--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.
-
-### mfe-publish
-
-This is an umbrella command for both publishing and unpublishing (cleaning up) MFEs. This command allows publishing MFEs in a way that there is no risk of colliding package versions (a common issue with back-merging). See the `--build` option for more details.
-
-#### Publishing options
-
-| Option              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--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.                                                                                                                                                                                                                                                                                           |
-| `--dry`             | Invoke [npm publish --dry-run](https://docs.npmjs.com/cli/v7/commands/npm-publish#dry-run) instead of 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `--force`           | Forces publishing the package when no configuration was found for the specified branch (`--branch` or current branch).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `--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". |
-
-#### Unpublishing options
-
-| Option             | Descripiton                                                                                                                                   |
-| :----------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--clean`          | Instructs `mfe-publish` to remove old versions instead of publishing.                                                                         |
-| `--count <number>` | The number of package versions to keep (e.g., if twelve versions are published, `--count 10` removes the two oldest). The default value is 5. |
-| `--branch <name>`  | Remove old versions associated with the specified branch. Defaults to the current branch (i.e., `git branch --show-current`)                  |
-| `--all`            | Remove old versions associated with all [recognized branches](#branch-configs). This overrides `--branch`.                                    |
-| `--dry`            | Log what the command would do without actually unpublishing anything.                                                                         |
-
-#### Branch configs
-
-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" },
-                "master": { "publishTag": "prod" }
-            }
-        }
-    }
-```
-
-- `publishTag: string` - Tag used when publishing package.
-
-### 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.
-
-#### Arguments
-
-- `--scope <glob>` - Include only packages with names matching the given glob.
-- `--ignore <glob>` - Exclude packages with names matching the given glob.
-- `--esbuild` - Use [esbuild-loader](https://github.com/privatenumber/esbuild-loader) to process TypeScript files instead of ts-loader.
-- `--experimental-bundlers` - Use experimental build optimizations (alternative loaders and bundlers)
-- `--code-coverage` - Add [instrumentation](https://github.com/JS-DevTools/coverage-istanbul-loader) to bundled code in order to collect code coverage
-
-### test
-
-Runs all existing tests in all packages.
-
-To run tests a subset of tests is possible to pass paths to specific directories or test files as positional parameters.
-
-```sh
-$ npx startup test -- packages/desktop/app/modules/inventory/
-```
-
-## Build Steps
-
-The `build` command executes these steps:
-
-1. For each non-webpack package, generate TypeScript definitions from CSS, LESS, and SASS modules, and copy assets and style files to the output folder. This step runs in parallel for each package.
-1. Compile non-webpack packages in order (via [TypeScript project references](https://www.typescriptlang.org/docs/handbook/project-references.html)).
-1. Bundle webpack packages, in parallel.
-
-The `start` command executes the same steps then watches for changes and automatically reruns each step as needed.
-
-#### Important Note
-
-It doesn't support hierarchical watch because we are not maintaining hierarchy ourselves, so we have to build everything first and then run watch when order is no longer important. Also, it doesn't support dependencies between the Webpack bundles.
-
-## Package Setup
-
-Because `startup` compiles and builds in separate steps, packages should export the compiled output instead of the TypeScript source files.
-
-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"
-{
-    "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
-
-Use the `cli` node in the root `package.json` to customize project-wide settings.
-
-#### Jest
-
-Use `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 `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
-
-Use `NODE_OPTIONS` to set or override Node options for some or all commands. E.g.,
-
-:::info
-Note, `startup` runs all commands with `--max_old_space_size=8192` by default.
-:::
-
-```json title="package.json"
-{
-    "cli": {
-        "NODE_OPTIONS": ["--max_old_space_size=4096"], // NODE_OPTIONS for all commands
-        "lint": {
-            "NODE_OPTIONS": [
-                /* NODE_OPTIONS for lint command */
-            ]
-        },
-        "test": {
-            "NODE_OPTIONS": [
-                /* NODE_OPTIONS for test command */
-            ]
-        }
-    }
-}
-```
-
-### Package-specific settings
-
-To customize the settings for a specific package, use the `cli` node in its `package.jon`.
-
-##### Non-application packages
-
-Set `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
-    }
-}
-```
-
-##### Microfrontends (MFEs)
-
-Set `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
-
-- `branches` - Set git branch specific configs, used for publishing. See [Branch configs](#branch-configs).
-- `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.
-
-##### 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 `minify.js` or `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 `minify.js` to an object containing
-[`terserOptions`](https://webpack.js.org/plugins/terser-webpack-plugin/#terseroptions).
-To override the default CssMinimizerWebpackPlugin options, set `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 `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 `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` (currently only `ForkTsCheckerWebpackPlugin` and `HtmlWebpackPlugin` are supported, and `MiniCssExtractPlugin` is only supported for production builds) with settings overrides for Webpack and its plugins. Returns default Webpack configuration for provided `configuration.mode` with applied overrides.
-
-```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: [...]
-};
-```