@servicetitan/docs-uikit 28.4.0 → 29.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/BREAKING_CHANGES.mdx +11 -0
- package/docs/ajax-handlers.mdx +67 -8
- package/docs/startup.mdx +42 -42
- package/package.json +2 -2
- package/docs/component-usage.mdx +0 -66
|
@@ -2,6 +2,17 @@
|
|
|
2
2
|
title: BREAKING CHANGES
|
|
3
3
|
---
|
|
4
4
|
|
|
5
|
+
## v29.0.0
|
|
6
|
+
|
|
7
|
+
### [@servicetitan/startup](./startup)
|
|
8
|
+
|
|
9
|
+
- Dropped support for Node 18.
|
|
10
|
+
Update Github workflows and Docker containers to use Node v20 or later, and bump the `engines.node` property in package.json files to >=20 or >=22.
|
|
11
|
+
|
|
12
|
+
- Added safeguards to mfe-publish to avoid accidentally deleting production bundles
|
|
13
|
+
- Changed `--clean` to never remove old versions that have a tag
|
|
14
|
+
- Changed the default behavior of `--clean` to only remove old versions from the current branch. Use `--branch` to remove old versions from a different branch and use `--all` to remove old versions from all branches.
|
|
15
|
+
|
|
5
16
|
## v28.0.0
|
|
6
17
|
|
|
7
18
|
### [@servicetitan/startup](./startup)
|
package/docs/ajax-handlers.mdx
CHANGED
|
@@ -61,7 +61,7 @@ const App = () => {
|
|
|
61
61
|
| Name | Type | Description |
|
|
62
62
|
| :------------------------ | :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
63
63
|
| `authAdapter` | <code>string | Function</code> | (optional) authentication scheme ([see below](#auth-adapter)). Defaults to **Bearer** authentication. |
|
|
64
|
-
| `authURL` | `string` | (optional) authentication endpoint for protected resources.
|
|
64
|
+
| `authURL` | `string` | (optional) authentication endpoint for protected resources. |
|
|
65
65
|
| `axiosInstance` | `AxiosInstance` | (optional) Axios instance which will be used for authenticated requests. Defaults to the global Axios |
|
|
66
66
|
| `baseURL` | `string` | base URL of protected resources |
|
|
67
67
|
| `component` | `React.ComponentType` | component to wrap |
|
|
@@ -74,19 +74,21 @@ const App = () => {
|
|
|
74
74
|
|
|
75
75
|
Use `authAdapter` to select the authentication scheme. One of,
|
|
76
76
|
|
|
77
|
-
| Value | Description
|
|
78
|
-
| :----------- |
|
|
79
|
-
| "bearer" | **Bearer** authentication sends the bearer token returned by `authURL` in the **Authorization** header of requests. |
|
|
80
|
-
| "token" | **Token** authentication uses the Token Server's "silent login" protocol to add secure cookies to requests. |
|
|
81
|
-
|
|
|
77
|
+
| Value | Description |
|
|
78
|
+
| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
79
|
+
| "bearer" | **Bearer** authentication sends the bearer token returned by `authURL` in the **Authorization** header of requests. Uses BearerTokenAuth adapter. |
|
|
80
|
+
| "token" | **Token** authentication uses the Token Server's "silent login" protocol to add secure cookies to requests. Uses TokenServerAuth adapter. |
|
|
81
|
+
| `(context: WithMicroserviceContext) => AuthAdapter` | Custom authentication uses the adapter returned by a function to decorate requests. |
|
|
82
|
+
|
|
83
|
+
See [Authentication Adapters](#authentication-adapters) for more information.
|
|
82
84
|
|
|
83
85
|
#### authUrl
|
|
84
86
|
|
|
85
87
|
The authentication endpoint for protected resources.
|
|
86
88
|
|
|
87
|
-
- For **Bearer** authentication, this is the endpoint that returns the bearer token to send in **Authorization** headers.
|
|
89
|
+
- For **Bearer** authentication, this is the endpoint that returns the bearer token to send in **Authorization** headers. Defaults to `${baseURL}/bff/silent-login`.
|
|
88
90
|
|
|
89
|
-
- For **Token server** authentication, this the "silent login" endpoint. Defaults to `${baseURL}/bff/silent-login`.
|
|
91
|
+
- For **Token server** authentication, this is the "silent login" endpoint. Defaults to `${baseURL}/bff/silent-login`.
|
|
90
92
|
|
|
91
93
|
#### preAuthenticate{#pre-authenticate}
|
|
92
94
|
|
|
@@ -136,6 +138,63 @@ const Component = () => {
|
|
|
136
138
|
}
|
|
137
139
|
```
|
|
138
140
|
|
|
141
|
+
### Authentication Adapters{#authentication-adapters}
|
|
142
|
+
|
|
143
|
+
`withMicroservice` uses authentication adapters in order to perform authentication in different ways depending on your needs.
|
|
144
|
+
|
|
145
|
+
#### BearerTokenAuth
|
|
146
|
+
|
|
147
|
+
The default adapter is the `BearerTokenAuth` adapter. When authentication occurs, a request is sent to the `authURL` in order to retrieve a token. Then any requests made using the `baseURL` will add the `Authorization: Bearer ...` header with the stored token.
|
|
148
|
+
|
|
149
|
+
`BearerTokenAuth` can be used by setting `authAdapter` to `'bearer'`.
|
|
150
|
+
|
|
151
|
+
```tsx
|
|
152
|
+
const App = withMicroservice({
|
|
153
|
+
authAdapter: 'bearer',
|
|
154
|
+
baseURL: '/api',
|
|
155
|
+
component: UnwrappedApp,
|
|
156
|
+
});
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
#### TokenServerAuth{#token-server-auth}
|
|
160
|
+
|
|
161
|
+
The `TokenServerAuth` adapter allows you to authenticate with a backend that is using the `ServiceTitan.Ium.Bff` NuGet package ([see TokenServer documentation for details](/docs/projects/ium/tokenserver-new-app-integration/)).
|
|
162
|
+
|
|
163
|
+
This adapter takes care of the silent login portion of the authentication process, setting the application session cookie when your component mounts. For more information about silent login, [view the documentation here](/docs/projects/ium/mfe-silent-login/).
|
|
164
|
+
|
|
165
|
+
If authentication fails (likely because the user is not logged in), the page is reloaded. You can customize this behavior by passing an `onError` function in `TokenServerAuth` options (see below).
|
|
166
|
+
|
|
167
|
+
`TokenServerAuth` can be used by setting `authAdapter` to `'token'`, or to a function that returns a new `TokenServerAuth` instance. Adapter specific options can be passed as the second parameter.
|
|
168
|
+
|
|
169
|
+
```tsx title="Default adapter"
|
|
170
|
+
const App = withMicroservice({
|
|
171
|
+
authAdapter: 'token',
|
|
172
|
+
baseURL: '/api',
|
|
173
|
+
component: UnwrappedApp,
|
|
174
|
+
});
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
```tsx title="Custom adapter"
|
|
178
|
+
const options: TokenServerAuthOptions = {
|
|
179
|
+
authInfoURL: '/custom/authinfo',
|
|
180
|
+
onError: (defaultErrorHandler) => {
|
|
181
|
+
console.error('There was an error');
|
|
182
|
+
defaultErrorHandler();
|
|
183
|
+
},
|
|
184
|
+
};
|
|
185
|
+
const App = withMicroservice({
|
|
186
|
+
authAdapter: context => new TokenServerAuth(context, options),
|
|
187
|
+
baseURL: '/api',
|
|
188
|
+
component: UnwrappedApp,
|
|
189
|
+
});
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
##### TokenServerAuthOptions
|
|
193
|
+
| Name | Type | Description |
|
|
194
|
+
| :------------ | :------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
195
|
+
| `authInfoURL` | `string` | (optional) URL to fetch authentication parameters from. Defaults to `'/bff/authinfo'`. |
|
|
196
|
+
| `onError` | `(defaultErrorHandler: () => void) => void;` | (optional) Callback to call when an error occurs during authentication. Defaults to reloading the page a maximum of 1 time. First parameter is a function to call the default error handler. |
|
|
197
|
+
|
|
139
198
|
### Authorization
|
|
140
199
|
|
|
141
200
|
`withMicroservice` currently only assists with performing authentication for requests of protected resources. There are currently no plans to implement authorization until we see concrete Token Server usage examples by product teams. If you find that having any sort of implementation for authorization would be helpful, especially in regards to Token Server implementation, please bring any ideas or discussions to the Frontend Platform team's attention so that we can create a platform solution.
|
package/docs/startup.mdx
CHANGED
|
@@ -46,11 +46,11 @@ Runs package in the development mode. Applications will be hosted on sequential
|
|
|
46
46
|
|
|
47
47
|
#### Arguments
|
|
48
48
|
|
|
49
|
-
-
|
|
50
|
-
-
|
|
51
|
-
-
|
|
52
|
-
-
|
|
53
|
-
-
|
|
49
|
+
- `--scope <glob>` - Include only packages with names matching the given glob.
|
|
50
|
+
- `--ignore <glob>` - Exclude packages with names matching the given glob.
|
|
51
|
+
- `--esbuild` - Use [esbuild-loader](https://github.com/privatenumber/esbuild-loader) to process TypeScript files instead of ts-loader.
|
|
52
|
+
- `--experimental-bundlers` - Use experimental build optimizations (alternative loaders and bundlers)
|
|
53
|
+
- `--code-coverage` - Add [instrumentation](https://github.com/JS-DevTools/coverage-istanbul-loader) to bundled code in order to collect code coverage
|
|
54
54
|
|
|
55
55
|
### build
|
|
56
56
|
|
|
@@ -58,13 +58,13 @@ Build packages for production to the `dist/bundle` folders. It bundles them in p
|
|
|
58
58
|
|
|
59
59
|
#### Arguments
|
|
60
60
|
|
|
61
|
-
-
|
|
62
|
-
-
|
|
63
|
-
-
|
|
64
|
-
-
|
|
65
|
-
-
|
|
66
|
-
-
|
|
67
|
-
-
|
|
61
|
+
- `--scope <glob>` - Include only packages with names matching the given glob.
|
|
62
|
+
- `--ignore <glob>` - Exclude packages with names matching the given glob.
|
|
63
|
+
- `--cdn-path <url>` - Specify the base path for all the assets within the application.
|
|
64
|
+
- `--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.
|
|
65
|
+
- `--esbuild` - Use [esbuild-loader](https://github.com/privatenumber/esbuild-loader) to process TypeScript files instead of ts-loader.
|
|
66
|
+
- `--experimental-bundlers` - Use experimental build optimizations (alternative loaders and bundlers)
|
|
67
|
+
- `--code-coverage` - Add [instrumentation](https://github.com/JS-DevTools/coverage-istanbul-loader) to bundled code in order to collect code coverage
|
|
68
68
|
|
|
69
69
|
### test
|
|
70
70
|
|
|
@@ -93,36 +93,41 @@ $ npx startup lint -- packages/desktop/app/modules/lead/ packages/desktop/app/mo
|
|
|
93
93
|
$ npx startup lint -- packages/desktop/app/modules/{lead,inventory}/
|
|
94
94
|
```
|
|
95
95
|
|
|
96
|
-
####
|
|
96
|
+
#### Options
|
|
97
97
|
|
|
98
|
-
-
|
|
99
|
-
-
|
|
100
|
-
-
|
|
98
|
+
- `--scope <glob>` - Include only packages with names matching the given glob.
|
|
99
|
+
- `--ignore <glob>` - Exclude packages with names matching the given glob.
|
|
100
|
+
- `--fix` - Fix linting issues.
|
|
101
101
|
|
|
102
102
|
### mfe-publish
|
|
103
103
|
|
|
104
|
-
This is an umbrella command for both unpublishing (cleaning up
|
|
105
|
-
|
|
106
|
-
#### Arguments
|
|
104
|
+
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.
|
|
107
105
|
|
|
108
|
-
|
|
106
|
+
#### Publishing options
|
|
109
107
|
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
108
|
+
| Option | Description |
|
|
109
|
+
| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
110
|
+
| `--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. |
|
|
111
|
+
| `--dry` | Invoke [npm publish --dry-run](https://docs.npmjs.com/cli/v7/commands/npm-publish#dry-run) instead of actually publishing anything. |
|
|
112
|
+
| `--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. |
|
|
113
|
+
| `--force` | Forces publishing the package when no configuration was found for the specified branch (`--branch` or current branch). |
|
|
114
|
+
| `--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". |
|
|
114
115
|
|
|
115
|
-
####
|
|
116
|
+
#### Unpublishing options
|
|
116
117
|
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
118
|
+
| Option | Descripiton |
|
|
119
|
+
| :----------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
120
|
+
| `--clean` | Instructs `mfe-publish` to remove old versions instead of publishing. |
|
|
121
|
+
| `--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. |
|
|
122
|
+
| `--branch <name>` | Remove old versions associated with the specified branch. Defaults to the current branch (i.e., `git branch --show-current`) |
|
|
123
|
+
| `--all` | Remove old versions associated with all [recognized branches](#branch-configs). This overrides `--branch`. |
|
|
124
|
+
| `--dry` | Log what the command would do without actually unpublishing anything. |
|
|
122
125
|
|
|
123
126
|
#### Branch configs
|
|
124
127
|
|
|
125
|
-
|
|
128
|
+
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.
|
|
129
|
+
|
|
130
|
+
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,
|
|
126
131
|
|
|
127
132
|
```json
|
|
128
133
|
"cli": {
|
|
@@ -136,15 +141,7 @@ To customize the publish tags for your MFE set `cli.web-component.branches` to a
|
|
|
136
141
|
}
|
|
137
142
|
```
|
|
138
143
|
|
|
139
|
-
-
|
|
140
|
-
|
|
141
|
-
#### Other auxiliary mfe-publish commands
|
|
142
|
-
|
|
143
|
-
In addition to `mfe-publish` also `mfe-package-clean` and `mfe-package-publish` commands are added.
|
|
144
|
-
|
|
145
|
-
`mfe-package-clean` command with a `--count` argument is equivalent to `mfe-publish` with `--count` and `--clean` arguments.
|
|
146
|
-
|
|
147
|
-
`mfe-package-publish` accepts all arguments mentioned above except for `--clean`, `--count`, and `--scope` i.e. this command only publishes packages.
|
|
144
|
+
- `publishTag: string` - Tag used when publishing package.
|
|
148
145
|
|
|
149
146
|
### kendo-ui-license
|
|
150
147
|
|
|
@@ -346,6 +343,7 @@ Set `web-component` to `true` to create the support files and `light` and `full`
|
|
|
346
343
|
```
|
|
347
344
|
|
|
348
345
|
Or you can set an object with detailed configs:
|
|
346
|
+
|
|
349
347
|
```json title="package.json"
|
|
350
348
|
{
|
|
351
349
|
"cli": {
|
|
@@ -359,6 +357,7 @@ Or you can set an object with detailed configs:
|
|
|
359
357
|
```
|
|
360
358
|
|
|
361
359
|
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):
|
|
360
|
+
|
|
362
361
|
```json title="package.json"
|
|
363
362
|
{
|
|
364
363
|
"cli": {
|
|
@@ -366,10 +365,11 @@ Or you can use relative path to a file that exports an object with detailed conf
|
|
|
366
365
|
}
|
|
367
366
|
}
|
|
368
367
|
```
|
|
368
|
+
|
|
369
369
|
###### Web component config options
|
|
370
370
|
|
|
371
|
-
-
|
|
372
|
-
-
|
|
371
|
+
- `branches` - Set git branch specific configs, used for publishing. See [Branch configs](#branch-configs).
|
|
372
|
+
- `legacyRoot` - Set to opt-out of automatic batching. See [Opting-out of automatic batching](/docs/frontend/react-18#opting-out-of-automatic-batching).
|
|
373
373
|
|
|
374
374
|
See [MFE configuration](/docs/frontend/micro-frontends/#mfe-configuration) for detailed instructions on configuring MFE applications.
|
|
375
375
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@servicetitan/docs-uikit",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "29.0.0",
|
|
4
4
|
"description": "",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -16,5 +16,5 @@
|
|
|
16
16
|
"cli": {
|
|
17
17
|
"webpack": false
|
|
18
18
|
},
|
|
19
|
-
"gitHead": "
|
|
19
|
+
"gitHead": "67b2763ad7c21532ea47c920974f87e8de433d32"
|
|
20
20
|
}
|
package/docs/component-usage.mdx
DELETED
|
@@ -1,66 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
title: Component Usage
|
|
3
|
-
---
|
|
4
|
-
|
|
5
|
-
#### [CHANGELOG (@servicetitan/component-usage)](https://github.com/servicetitan/uikit/blob/master/packages/component-usage/CHANGELOG.md)
|
|
6
|
-
|
|
7
|
-
`@servicetitan/component-usage` will calculate and publish metrics on the app's component usage. The packages which we report on are currently hard-coded to [this list](https://github.com/servicetitan/uikit/blob/master/packages/component-usage/src/index.ts#L40-L64)
|
|
8
|
-
|
|
9
|
-
## Usage
|
|
10
|
-
|
|
11
|
-
### Basic Usage
|
|
12
|
-
|
|
13
|
-
```
|
|
14
|
-
$ npm install --save-dev @servicetitan/component-usage
|
|
15
|
-
$ npx component-usage
|
|
16
|
-
```
|
|
17
|
-
|
|
18
|
-
Or for one-time use with no installation:
|
|
19
|
-
|
|
20
|
-
```
|
|
21
|
-
$ npx @servicetitan/component-usage
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
### Options
|
|
25
|
-
|
|
26
|
-
You must specify at least one "mode" option: `--sendToDataDog`, `--outputDir`, `--teamCityOutput`.
|
|
27
|
-
|
|
28
|
-
The examples below show the long form of each option (like `--sendToDataDog`), but short forms are available (like `-s`). To see all the long and short options, use `--help`.
|
|
29
|
-
|
|
30
|
-
Display help:
|
|
31
|
-
|
|
32
|
-
```
|
|
33
|
-
$ npx @servicetitan/component-usage --help
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
Generate stats files locally in the current directory:
|
|
37
|
-
|
|
38
|
-
```
|
|
39
|
-
$ npx @servicetitan/component-usage --outputDir .
|
|
40
|
-
```
|
|
41
|
-
|
|
42
|
-
Send metrics to DataDog:
|
|
43
|
-
|
|
44
|
-
```
|
|
45
|
-
$ npx @servicetitan/component-usage --sendToDataDog --dataDogApiKey ...API_KEY_GOES_HERE... --dataDogApplicationKey ...APP_KEY_GOES_HERE...
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
Porque no los dos?
|
|
49
|
-
|
|
50
|
-
```
|
|
51
|
-
$ npx @servicetitan/component-usage --outputDir . --sendToDataDog --dataDogApiKey ...API_KEY_GOES_HERE... --dataDogApplicationKey ...APP_KEY_GOES_HERE...
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
TeamCity output
|
|
55
|
-
|
|
56
|
-
```
|
|
57
|
-
$ npx @servicetitan/component-usage --teamCityOutput
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
## Live Data
|
|
61
|
-
|
|
62
|
-
We currently have a [TeamCity build that triggers with every merge to master](https://teamcity.st.dev/viewType.html?buildTypeId=FrontendPlatform_ComponentUsageMaster) which specifies all three mode options:
|
|
63
|
-
|
|
64
|
-
- `--sendToDataDog`: publish the metric `far.componentUsage` to DataDog. [This DataDog dashboard](https://app.datadoghq.com/dashboard/my4-ftr-xgu/front-end-component-usage?from_ts=1602016753361&live=true&to_ts=1602103153361) shows some charts on this metric.
|
|
65
|
-
- `--outputDir`: write the stats out as files during the build, which is then published as a build artifact. [Example artifacts from a recent build](https://teamcity.st.dev/repository/download/FrontendPlatform_ComponentUsageMaster/901050:id/treemap/index.html)
|
|
66
|
-
- `--teamCityOutput`: write out special output during the TeamCity build process (like `##teamcity[buildStatisticValue...`) which gets captured and published as a TeamCity build statistic. See the [build statistics tab](https://teamcity.st.dev/viewType.html?buildTypeId=FrontendPlatform_ComponentUsageMaster&tab=buildTypeStatistics) for charts.
|