@servicetitan/docs-uikit 30.3.1 → 31.1.0

package/docs/startup/startup.mdx

@@ -0,0 +1,435 @@
+---
+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
+
+- [build](./build) build project for production
+- [clean](./clean) resets project to fresh state
+- [convert-eslint-config](./convert-eslint-config) convert v8.x eslintrc.json to v9.x flat config
+- [init](./init) create example project
+- [install](./install) install project dependencies
+- [kendo-ui-license](./kendo-ui-license) install KendoReact license key
+- [lint](./lint) run eslint and stylelint
+- [mfe-publish](./mfe-publish) publish or unpublish MFE packages
+- [review](./review) check project for configuration errors
+- [start](./start) run project in development mode
+- [test](./test) run tests
+
+## 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"
+{
+    "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
+
+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": {
+        "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
+
+#### 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).
+:::
+
+```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](#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.mdx

@@ -0,0 +1,11 @@
+---
+title: 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/
+```

package/docs/web-components/headless-loader.mdx

@@ -0,0 +1,67 @@
+---
+title: HeadlessLoader
+---
+
+The headless bundle is a tiny bundle that allows a host to preload configuration or setup information without having to load the entire MFE. The headless bundle does not utilize React, and cannot use any modules that require React.
+
+## Generating headless bundle
+
+To generate a headless bundle, create a file named `headless.ts` in the root directory of the MFE's source folder. When this file is present, startup generates a `headless` bundle alongside the `light` and `full` bundles. Only what is imported in `headless.ts` will be included in the bundle.
+
+`headless.ts` should contain exported functions named `connectedCallback` and/or `disconnectedCallback`.
+
+### `connectedCallback`
+
+`connectedCallback` will be called when the bundle is loaded in the host. It should be typed as `HeadlessCallback<T>`.
+
+```ts title="src/headless.ts"
+import type { HeadlessCallback } from '@servicetitan/web-components';
+export const connectedCallback: HeadlessCallback<ExampleData> = ({ mfeData, eventBus }) => {
+    doSomethingWithMfeData(mfeData);
+    eventBus?.emit('example-module:status', { status: 'connected', timestamp: Date.now() });
+};
+```
+
+
+### `disconnectedCallback`
+
+`disconnectedCallback` will be called when the headless MFE is unmounted. It should be typed as `HeadlessCallback<T>`.
+
+```ts title="src/headless.ts"
+import type { HeadlessCallback } from '@servicetitan/web-components';
+export const disconnectedCallback: HeadlessCallback = ({ eventBus }) => {
+    eventBus?.emit('example-module:status', { status: 'disconnected', timestamp: Date.now() });
+};
+```
+
+### `HeadlessCallback<T>`
+
+The `HeadlessCallback<T>` type is a function that receives an object with the below properties:
+
+| Parameter    | Type              | Description                                                                                    |
+| ------------ | ----------------- | ---------------------------------------------------------------------------------------------- |
+| `ldService`  | `LDService`       | The [LaunchDarkly LDService instance](../launchdarkly-service#ldservice) passed from the Host. |
+| `logService` | `Log`             | The [Log instance](../log-service#log) passed from the Host.                                       |
+| `eventBus`   | `EventBus`        | The [EventBus instance](./event-bus) passed from the Host.                                     |
+| `mfeData`    | `Serializable<T>` | The [data passed from the host into `HeadlessLoader`](#headless-loader-props), typed as `T`.   |
+
+## HeadlessLoader
+
+Use the `HeadlessLoader` component to load this bundle from within a host application.
+
+```tsx
+import { HeadlessLoader } from '@servicetitan/web-components';
+
+export const Foo = () => {
+    return <HeadlessLoader src="https://unpkg.servicetitan.com/{package_name}@{semver_range}" />;
+};
+```
+
+### Props  {#headless-loader-props}
+
+| Name          | Description                                                                                                                                         |
+| :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src`         | url for the MFE's package                                                                                                                           |
+| `fallbackSrc` | optional alternative url for the MFE's package (if request for src returns error)                                                                   |
+| `data`        | additional data passed to an MFE as an object, where values are serializable, and preferably memoized ([see Loader](./loader#passing-data-from-host-to-mfe)) |
+| `cache`       | optional cache strategy for the MFE [(see Loader)](./loader#cache-strategy). Defaults to `-1`.                                                               |