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

docs: add package roles sections to build system docs

Browse Source 
Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
This commit is contained in:
Patrik Oldsberg
2022-03-08 14:09:33 +01:00
parent d06d67bf8a
commit 4431319f45
2 changed files with 48 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/local-dev/cli-build-system.md
+47
View File
@@ -72,6 +72,53 @@ or IDE that has support for formatting, linting, and type checking.
Let's dive into a detailed look at each of these steps and how they are
implemented in a typical Backstage app.
## Package Roles
> Package roles were introduced in March 2022. To migrate existing projects, see the [migration guide](../tutorials/package-role-migration.md).
The Backstage build system uses the concept of package roles in order to help keep
configuration lean, provide utility and tooling, and enable optimizations. A package
role is a single string that identifies what the purpose of a package is, and it's
define in the `package.json` of each package like this:
```json
{
"name": "my-package",
"backstage": {
"role": "<role>"
},
...
}
```
These are the available roles that are currently supported by the Backstage build system:
| Role | Description | Example |
| ---------------------- | -------------------------------------------- | -------------------------------------------- |
| frontend | Bundled frontend application | `package/app` |
| backend | Bundled backend application | `packages/backend` |
| cli | Package used as a command-line interface | `@backstage/cli`, `@backstage/codemods` |
| web-library | Web library for use by other packages | `@backstage/plugin-catalog-react` |
| node-library | Node.js library for use by other packages | `@backstage/plugin-techdocs-node` |
| common-library | Isomorphic library for use by other packages | `@backstage/plugin-permission-common` |
| frontend-plugin | Backstage frontend plugin | `@backstage/plugin-scaffolder` |
| frontend-plugin-module | Backstage frontend plugin module | `@backstage/plugin-analytics-module-ga` |
| backend-plugin | Backstage backend plugin | `@backstage/plugin-auth-backend` |
| backend-plugin-module | Backstage backend plugin module | `@backstage/plugin-search-backend-module-pg` |
Most of the steps that we cover below have an accompanying command that is intended to be used as a package script. The commands are all available under the `backstage-cli package` category, and many of the commands will behave differently depending on the role of the package. The commands are intended to be used like this:
```json
{
"scripts": {
"start": "backstage-cli package start",
"build": "backstage-cli package build",
"lint": "backstage-cli package lint",
...
}
}
```
## Formatting
The formatting setup lives completely within each Backstage application and is
docs/tutorials/package-role-migration.md
+1 -1
View File
@@ -60,7 +60,7 @@ based on existing information like what build scripts are in place and the packa
This automatic detection is not perfect, so it recommended to manually review the
roles that were assigned to each package.
You can use the [package role definitions](./not-found#TODO) as a reference.
You can use the [package role definitions](../local-dev/cli-build-system#package-roles) as a reference.
### Step 2 - Migrate package scripts