paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 14 Packages Projects Releases Wiki Activity

docs/local-dev: add docs for the experimental type build

Browse Source 
Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
This commit is contained in:
Patrik Oldsberg
2022-03-01 17:54:56 +01:00
parent f587dcc5bf
commit 8dc290872d
1 changed files with 33 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/local-dev/cli-build-system.md
+33
View File
@@ -552,3 +552,36 @@ The following is an excerpt of a typical setup of an isomorphic library package:
},
"files": ["dist"],
```
## Experimental Type Build
The Backstage CLI has an experimental feature where multiple different type definition files can be generated for different release stages. The release stages are marked in the [TSDoc](https://tsdoc.org/) for each individual export, using either `@public`, `@alpha`, or `@beta`. Rather than just building a single `index.d.ts` file, the build process will instead output `index.d.ts`, `index.beta.d.ts`, and `index.alpha.d.ts`. Each of these files will have exports from more unstable release stages stripped, meaning that `index.d.ts` will omit all exports marked with `@alpha` or `@beta`, while `index.beta.d.ts` will omit all exports marked with `@alpha`.
This feature is aimed at projects that publish to package registries and wish to maintain different levels of API stability within each package. There is no need to use this within a single monorepo, as it has no effect due to only applying to built and published packages.
In order for the experimental type build to work, `@microsoft/api-extractor` must be installed in your project, as it is an optional peer dependency of the Backstage CLI. There are then three steps that need to be taken for each package where you want to enable this feature:
- Add the `--experimental-type-build` flag to the `"build"` script of the package.
- Add either one or both of `"alphaTypes"` and `"betaTypes"` to the `"publishConfig"` of the package:
```json
"publishConfig": {
...
"types": "dist/index.d.ts",
"alphaTypes": "dist/index.alpha.d.ts",
"betaTypes": "dist/index.beta.d.ts"
},
```
- Add either one or both of `"alpha"` and `"beta"` to the `"files"` of the package:
```json
"files": [
"dist",
"alpha",
"beta"
]
```
Once this setup is complete, users of the published packages will only be able to access the stable API via the main package entry point, for example `@acme/my-plugin`. Exports marked with `@alpha` or `@beta` will only be available via the `/alpha` entry point, for example `@acme/my-plugin/alpha`, and exports marked with `@beta` will only be available via `/beta`. This does not apply within the monorepo that contains the package. There all exports still have to be imported via the main entry point.
Note that these different entry points are only separated during type checking. At runtime they all share the same code which contains the exports from all releases stages.
An example of this setup can be seen in the [`@backstage/catalog-model`](https://github.com/backstage/backstage/blob/da0675bf9f28ed1460f03635a22d3c26abd14707/packages/catalog-model/package.json#L14) package, which has enabled `alpha` type exports. With this setup, exports marked as `@alpha` are only available for import via `@backstage/catalog-model/alpha`. The `@backstage/catalog-model` package currently does not have any exports marked as `@beta`, or a `/beta` entry point.