@servicetitan/docs-uikit 27.4.0 → 28.1.0

package/docs/BREAKING_CHANGES.mdx

@@ -2,6 +2,12 @@
 title: BREAKING CHANGES
 ---
 
+## v28.0.0
+
+### [@servicetitan/startup](./startup)
+
+-   Changed the default [moduleResolution](https://www.typescriptlang.org/tsconfig/#moduleResolution) from `node` to `bundler` to support importing from `@servicetitan/anvil2/token`. CommonJS packages that require the previous value must override `moduleResolution` in the package's `tsconfig.json`.
+
 ## v27.0.0
 
 ### [@servicetitan/startup](./startup)

package/docs/startup.mdx

@@ -30,19 +30,15 @@ Experimental flags don't follow semver. There might be breaking changes in minor
 
 Generates initial project structure. This command should be run via `npx` in an empty folder.
 
+```sh
+$ npx -y @servicetitan/startup@latest init
 ```
-npx -y @servicetitan/startup@latest init
-```
-
-#### Arguments
-
--   `--react17` - Generate a project that uses React 17.x instead of React 18.x
 
 ### install
 
 Installs the package dependencies. This command should be run via `npx` before the build.
 
-See [configuration example in the `init` template](https://github.com/servicetitan/uikit/blob/master/packages/startup/template/package.json)
+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).
 
 ### start
 
@@ -77,7 +73,7 @@ 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
-startup test -- packages/desktop/app/modules/inventory/
+$ npx startup test -- packages/desktop/app/modules/inventory/
 ```
 
 ### lint
@@ -87,14 +83,14 @@ 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
-startup lint -- packages/desktop/app/modules/inventory/
+$ npx startup lint -- packages/desktop/app/modules/inventory/
 ```
 
 You can use multiple paths and your shell expressions which expand to directories.
 
 ```sh
-startup lint -- packages/desktop/app/modules/lead/ packages/desktop/app/modules/inventory/
-startup lint -- packages/desktop/app/modules/{lead,inventory}/
+$ npx startup lint -- packages/desktop/app/modules/lead/ packages/desktop/app/modules/inventory/
+$ npx startup lint -- packages/desktop/app/modules/{lead,inventory}/
 ```
 
 #### Arguments
@@ -113,6 +109,8 @@ This is an umbrella command for both unpublishing (cleaning up, `mfe-package-cle
 
 -   `--clean` - Start the clean-up script instead of publishing.
 -   `--count <number>` - The number of packages to be unpublished (cleaned up). The default value is 5. This argument has effect only when `--clean` is specified too.
+-   `--branch` - Clean versions related to the current git branch. This argument has effect only when `--clean` is specified too.
+-   `--branch <branch_name>` - Clean versions related to the specified git branch. This argument has effect only when `--clean` is specified too.
 
 #### Publish arguments
 
@@ -120,8 +118,25 @@ This is an umbrella command for both unpublishing (cleaning up, `mfe-package-cle
 -   `--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` - Attempts to force publish the package in case no branch configuration is found for the specified branch (`--branch` or current branch).
--   `--tag <string> | false` - If the value is `false` the package will be published without a custom [tag](https://docs.npmjs.com/cli/v7/commands/npm-publish#tag) (meaning it will be published with the default `latest` tag). If another value is specified it will be used as the tag name otherwise the tag value will be mapped from [following object](https://github.com/servicetitan/uikit/blob/master/packages/startup/src/cli/commands/mfe-publish.ts#L311-L316). For example, in case of branch name `master` the package will be published with the `prod` tag, etc.
--   `--noTag <string>` - This argument is currently not used.
+-   `--tag <string> | false` - If the value is `false` the package will be published without a custom [tag](https://docs.npmjs.com/cli/v7/commands/npm-publish#tag) (meaning it will be published with the default `latest` tag). If another value is specified it will be used as the tag name otherwise the tag value will be mapped from [branch configs](#branch-configs). If no branch configs specified, tag value will be mapped from [following object](https://github.com/servicetitan/uikit/blob/master/packages/startup/src/utils/get-branch-configs.ts#L3). For example, in case of branch name `master` the package will be published with the `prod` tag, etc.
+
+#### Branch configs
+
+To customize the publish tags for your MFE set `cli.web-component.branches` to an object that maps branch names to the associated tags. For example,
+
+```json
+    "cli": {
+        "web-component": {
+            "branches": {
+                "qa": { "publishTag": "qa" },
+                "staging": { "publishTag": "staging" },
+                "master": { "publishTag": "prod" }
+            }
+        }
+    }
+```
+
+-   `publishTag: string` - Tag used when publishing package.
 
 #### Other auxiliary mfe-publish commands
 
@@ -150,16 +165,45 @@ $ export KENDO_UI_LICENSE=<license-key>
 $ npx startup kendo-ui-license
 ```
 
-## Build Stages
+## Build Steps
+
+The `build` command executes these steps:
 
-1. Generation of TypeScript definition files from CSS, LESS, and SASS Modules (by `typed-css-modules`) for each Lerna package and copying all assets and style files to the `dist` folder for each non-webpack Lerna package in parallel.
-1. Building all non-webpack Lerna packages by TypeScript CLI in hierarchical order via [TypeScript project references](https://www.typescriptlang.org/docs/handbook/project-references.html).
-1. Running Webpack bundling for each webpack Lerna package in parallel.
+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.
@@ -301,6 +345,23 @@ Set `web-component` to `true` to create the support files and `light` and `full`
 }
 ```
 
+Or you can set an object with detailed configs:
+```json title="package.json"
+{
+    "cli": {
+        "web-component": {
+            "branches": {
+                "qa": { "publishTag": "qa" }
+            }
+        }
+    }
+}
+```
+###### 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

package/docs/web-components.mdx

@@ -41,7 +41,7 @@ export const Foo: React.FC = () => {
 | `loadingFallbackDelayed` | controls whether to render the loading fallback immediately, or after a short delay [(see below)](#fallback-delay)                                  |
 | `errorFallback`          | optional JSX element to render when the MFE fails to load                                                                                           |
 | `className`              | additional CSS classes for the MFE web component element                                                                                            |
-| `cache`                  | optional cache strategy for the MFE [(see below)](#cache)                                                                                           |
+| `cache`                  | optional cache strategy for the MFE [(see below)](#cache-strategy)                                                                                  |
 
 #### Loading fallback delay {#fallback-delay}
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@servicetitan/docs-uikit",
-    "version": "27.4.0",
+    "version": "28.1.0",
     "description": "",
     "repository": {
         "type": "git",
@@ -16,5 +16,5 @@
     "cli": {
         "webpack": false
     },
-    "gitHead": "0d58d7916d659a9617a12df86cdd183b5d49eef2"
+    "gitHead": "27d173aad0e016014bed59385886d0fd7ca3fb17"
 }