From 793e720bc7b5996b8ed238e3daf24c16dcc89a7d Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 8 Mar 2022 13:09:56 +0100 Subject: [PATCH 01/15] docs: added initial package role migration docs Signed-off-by: Patrik Oldsberg --- docs/tutorials/package-role-migration.md | 143 +++++++++++++++++++++++ microsite/sidebars.json | 1 + mkdocs.yml | 1 + 3 files changed, 145 insertions(+) create mode 100644 docs/tutorials/package-role-migration.md diff --git a/docs/tutorials/package-role-migration.md b/docs/tutorials/package-role-migration.md new file mode 100644 index 0000000000..76847d47b1 --- /dev/null +++ b/docs/tutorials/package-role-migration.md @@ -0,0 +1,143 @@ +--- +id: package-role-migration +title: Package Role Migration +description: Guide for how to migrate packages to use the new role utility +--- + +The Backstage CLI has introduced the concept of package roles, whose purpose is to +enable more powerful tooling and leaner package configuration. More background and +information about the change can be found in the [original RFC](https://github.com/backstage/backstage/issues/8729). + +Package roles are implemented through a well-known `"backstage"."role"` field in the +`package.json` of each package. There are a handful of roles defined so far, and it +is not possible to use value outside the set of predefined roles. Some examples of +these roles are `frontend-plugin`, `node-library`, and `backend-plugin-module`. + +With roles in place in all packages, the Backstage CLI is able to automatically +determine how to handle each package. For example, the different build commands +have been replaced by a single one that instead knows how to build each role. +The test and lint configurations are also selected automatically based on the role, and +a new category of `repo` commands have been introduced in the CLI, which are able +to operate across all packages at once. + +Package roles have been used in the Backstage main repository for a while, and +we now recommend that all Backstage projects are migrated to use package roles. + +## Migration + +In order to make the migration as smooth as possible, `@backstage/cli` provides +a number of migration utilities. Using these in combination with some manual review +and optional steps should be all you need to migrate to package roles in most projects. + +Before you begin the migration, make sure you have updated to the most recent version of +the `@backstage/cli`. + +### TL;DR, Step 1-4: + +This is a sorter version of all of the steps below, in case you're in a hurry. + +Run the following commands: + +```sh +yarn backstage-cli migrate package-roles +yarn backstage-cli migrate package-scripts +yarn backstage-cli migrate package-lint-configs +``` + +Have a look at the new commands under `yarn backstage-cli repo`, and switch to them wherever you can. They tend to be a much faster compared to their `lerna` equivalents. + +### Step 1 - Add package roles + +The first step is to add the `"backstage"."role"` field to each package. This +is done by running the following command: + +```sh +yarn backstage-cli migrate package-roles +``` + +This will add the role field to each package in your project, detecting the role +based on existing information like what build scripts are in place and the package name. + +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. + +### Step 2 - Migrate package scripts + +The migration to package roles also introduces a new `package` command category to the CLI. +Each command under the `package` category is designed to be mapped directly to an entry in `"scripts"` in `package.json`. These commands replace the existing commands like `build`, `app:build`, `lint` and `test`. They look something like this: + +```json +{ + "scripts": { + "start": "backstage-cli package start", + "build": "backstage-cli package build", + "lint": "backstage-cli package lint", + ... + } +} +``` + +Every package role each has a fixed set of recommended scripts. It is strongly recommended that you use these scripts, as it allows for optimizations in other parts of the CLI. You can migrate to using all of these scripts by running the following command: + +```sh +yarn backstage-cli migrate package-scripts +``` + +The migration command also carries over any existing flags that were being passed in the old scripts. + +If you in the end do not want to use this exact script setup, it is still recommended to migrate to using the `package` commands, as the top-level commands will be deprecated and removed. If you don't want to use package roles either, you can pass an explicit role to some of the package commands, for example `yarn backstage-cli package build --role web-library`. + +### Step 3 - Migrate package ESLint configurations + +An area that has been simplified as part of the move to package roles is the ESLint configuration. Rather than having each package select which configuration they want (and getting it wrong), they now use a shared configuration factory that utilizes the package role. + +A minimal `.eslintrc.js` configuration now looks like this: + +```js +module.exports = require('@backstage/cli/config/eslint-factory')(__dirname); +``` + +You can provide custom overrides for each package using the optional second argument: + +```js +module.exports = require('@backstage/cli/config/eslint-factory')(__dirname, { + ignorePatterns: ['templates/'], + rules: { + 'jest/expect-expect': 'off', + }, +}); +``` + +The configuration factory also provides utilities for extending the configuration in ways that are otherwise very cumbersome to do with plain ESLint, particularly for rules like `no-restricted-syntax`. You can read more about that in the [build system documentation](./not-found#TODO). + +To migrate the ESLint configuration of all packages in your project, run the following command: + +```sh +yarn backstage-cli migrate package-lint-configs +``` + +This will migrate all existing `.eslintrc.js` that extend the old configuration from `@backstage/cli`, as well as carry over any additional configuration. + +### Step 4 - Use `backstage-cli repo` + +The Backstage CLI recently introduced a new `repo` command category, which houses commands that operate on an entire monorepo at once. These commands work particularly well once packages have been migrated to use roles, as that allows for some very effective optimizations. It is typically much faster to use these commands compared to using tools like `lerna`, as they're able to avoid the overhead of calling package scripts through `yarn`. You can read more about the `repo` command in the [CLI command documentation](./not-found#TODO). + +The way to execute this step of the migration is not as well defined as the previous steps, as it depends on what your development and CI/CD setup looks like. Look for the following patterns to replace in your root `package.json` as well as CI/CD setup: + +- Commands that lint the entire repo should be replaced with `yarn backstage-cli repo lint` along with a `--since` flag if needed. For example this: + + ```sh + lerna run lint --since origin/master -- + ``` + + would be replaced by the following: + + ```sh + backstage-cli repo lint --since origin/master + ``` + +- In places where the entire repo is being built, use `yarn backstage-cli repo build`, which also supports the `--since` flag. The migration here is a bit more nuanced as it depends why you are building all packages. + - If you are building all packages to **verify** that you are able to build them, you most likely want `backstage-cli repo build --all`. The `--all` flag signals that bundled packages like `packages/app` and `packages/backend` should be build as well. Pair this up with a `--since` flag in CI to avoid needing to build all packages. + - If you are building all packages to **publish** them, then `backstage-cli repo build` is enough, as it builds all published packages. + - If you are building all packages to **deploy** them, you likely don't want to use the `repo` command at all, simply call `yarn build` in the packages you want to deploy instead. For example, if you are deploying the backend with a docker host build, it's enough to call `yarn build` inside `packages/backend`. diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 5369182013..1d409ae051 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -273,6 +273,7 @@ "Tutorials": [ "tutorials/journey", "tutorials/quickstart-app-plugin", + "tutorials/package-role-migration", "tutorials/migrating-away-from-core", "tutorials/configuring-plugin-databases", "tutorials/switching-sqlite-postgres", diff --git a/mkdocs.yml b/mkdocs.yml index 4671a10b7a..65e1a85bb4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -170,6 +170,7 @@ nav: - Deprecations: 'api/deprecations.md' - Tutorials: - Future developer journey: 'tutorials/journey.md' + - Package Role Migration: 'tutorials/package-role-migration.md' - Migrating away from @backstage/core: 'tutorials/migrating-away-from-core.md' - Adding Custom Plugin to Existing Monorepo App: 'tutorials/quickstart-app-plugin.md' - Switching Backstage from SQLite to PostgreSQL: 'tutorials/switching-sqlite-postgres.md' From d06d67bf8afe63e67ddcb5ee1aff067f8d08d994 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 8 Mar 2022 13:33:34 +0100 Subject: [PATCH 02/15] docs: add package role migration FAQ Signed-off-by: Patrik Oldsberg --- docs/tutorials/package-role-migration.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/tutorials/package-role-migration.md b/docs/tutorials/package-role-migration.md index 76847d47b1..2aee853673 100644 --- a/docs/tutorials/package-role-migration.md +++ b/docs/tutorials/package-role-migration.md @@ -141,3 +141,22 @@ The way to execute this step of the migration is not as well defined as the prev - If you are building all packages to **verify** that you are able to build them, you most likely want `backstage-cli repo build --all`. The `--all` flag signals that bundled packages like `packages/app` and `packages/backend` should be build as well. Pair this up with a `--since` flag in CI to avoid needing to build all packages. - If you are building all packages to **publish** them, then `backstage-cli repo build` is enough, as it builds all published packages. - If you are building all packages to **deploy** them, you likely don't want to use the `repo` command at all, simply call `yarn build` in the packages you want to deploy instead. For example, if you are deploying the backend with a docker host build, it's enough to call `yarn build` inside `packages/backend`. + +## FAQ + +### Why where packages roles introduced? + +To keep configuration lean, allow for more utilities and tooling, and to enable optimizations in the build system. You can read more about the reasoning in the [original RFC](https://github.com/backstage/backstage/issues/8729). + +### Do I have to migrate to using package roles? + +Short answer - yes. +Longer answer - mostly, you can get around having to declare package the role of your packages by instead explicitly declaring the role in the command invocation or configuration. For example, the `app:build` command will go away, but you can replace it with `package build --role frontend` if you don't want to declare the role in `package.json` . It is however strongly recommended to declare the package roles. + +### I have a package where none of the existing roles apply + +The `web-library`, `node-library` and `common-library` roles are general purpose roles that should cover most use cases. If you feel like none of those roles work for you either, then please open an issue in the [Backstage repo](https://github.com/backstage/backstage) and suggest the addition of a new role. + +### Should I include the role in published packages? + +Yes. While there is nothing that will consume the role at the moment, it is likely that future tooling will be able to provide a better experience for users when published packages include the role. From 4431319f4531f9a51a932152313a237c7b7685e8 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 8 Mar 2022 14:09:33 +0100 Subject: [PATCH 03/15] docs: add package roles sections to build system docs Signed-off-by: Patrik Oldsberg --- docs/local-dev/cli-build-system.md | 47 ++++++++++++++++++++++++ docs/tutorials/package-role-migration.md | 2 +- 2 files changed, 48 insertions(+), 1 deletion(-) diff --git a/docs/local-dev/cli-build-system.md b/docs/local-dev/cli-build-system.md index aed3ba70bc..eef0a68af0 100644 --- a/docs/local-dev/cli-build-system.md +++ b/docs/local-dev/cli-build-system.md @@ -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": "" + }, + ... +} +``` + +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 diff --git a/docs/tutorials/package-role-migration.md b/docs/tutorials/package-role-migration.md index 2aee853673..bdc50fc54d 100644 --- a/docs/tutorials/package-role-migration.md +++ b/docs/tutorials/package-role-migration.md @@ -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 From 8a5ff40dcd1f82453071d2f8830dfb9af43dcabe Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 8 Mar 2022 14:11:38 +0100 Subject: [PATCH 04/15] docs: update lint section in build system docs Signed-off-by: Patrik Oldsberg --- docs/local-dev/cli-build-system.md | 35 ++++++++++++++++++++++-- docs/tutorials/package-role-migration.md | 21 +------------- 2 files changed, 33 insertions(+), 23 deletions(-) diff --git a/docs/local-dev/cli-build-system.md b/docs/local-dev/cli-build-system.md index eef0a68af0..4b8d2410dc 100644 --- a/docs/local-dev/cli-build-system.md +++ b/docs/local-dev/cli-build-system.md @@ -143,9 +143,38 @@ configurations in turn build on top of the lint rules from In a standard Backstage setup, each individual package has its own lint configuration, along with a root configuration that applies to the entire -project. Each configuration is initially one that simply extends a base -configuration provided by the Backstage CLI, but they can be customized to fit -the needs of each package. +project. The configuration in each package starts out as a standard configuration +that is determined based on the package role, but it can be customized to fit the needs of each package. + +A minimal `.eslintrc.js` configuration now looks like this: + +```js +module.exports = require('@backstage/cli/config/eslint-factory')(__dirname); +``` + +But you can provide custom overrides for each package using the optional second argument: + +```js +module.exports = require('@backstage/cli/config/eslint-factory')(__dirname, { + ignorePatterns: ['templates/'], + rules: { + 'jest/expect-expect': 'off', + }, +}); +``` + +The configuration factory also provides utilities for extending the configuration in ways that are otherwise very cumbersome to do with plain ESLint, particularly for rules like `no-restricted-syntax`. These are the extra keys that are available: + +| Key | Description | +| ----------------------- | ------------------------------------------------------------------ | +| `tsRules` | Additional rules to apply to TypeScript files | +| `testRules` | Additional rules to apply to tests files | +| `restrictedImports` | Additional paths to add to `no-restricted-imports` | +| `restrictedSrcImports` | Additional paths to add to `no-restricted-imports` in src files | +| `restrictedTestImports` | Additional paths to add to `no-restricted-imports` in test files | +| `restrictedSyntax` | Additional patterns to add to `no-restricted-syntax` | +| `restrictedSrcSyntax` | Additional patterns to add to `no-restricted-syntax` in src files | +| `restrictedTestSyntax` | Additional patterns to add to `no-restricted-syntax` in test files | ## Type Checking diff --git a/docs/tutorials/package-role-migration.md b/docs/tutorials/package-role-migration.md index bdc50fc54d..d9d9c8c91a 100644 --- a/docs/tutorials/package-role-migration.md +++ b/docs/tutorials/package-role-migration.md @@ -90,26 +90,7 @@ If you in the end do not want to use this exact script setup, it is still recomm ### Step 3 - Migrate package ESLint configurations -An area that has been simplified as part of the move to package roles is the ESLint configuration. Rather than having each package select which configuration they want (and getting it wrong), they now use a shared configuration factory that utilizes the package role. - -A minimal `.eslintrc.js` configuration now looks like this: - -```js -module.exports = require('@backstage/cli/config/eslint-factory')(__dirname); -``` - -You can provide custom overrides for each package using the optional second argument: - -```js -module.exports = require('@backstage/cli/config/eslint-factory')(__dirname, { - ignorePatterns: ['templates/'], - rules: { - 'jest/expect-expect': 'off', - }, -}); -``` - -The configuration factory also provides utilities for extending the configuration in ways that are otherwise very cumbersome to do with plain ESLint, particularly for rules like `no-restricted-syntax`. You can read more about that in the [build system documentation](./not-found#TODO). +An area that has been simplified as part of the move to package roles is the ESLint configuration. Rather than having each package select which configuration they want (and getting it wrong), they now use a shared configuration factory that utilizes the package role. You can read more about the new configuration setup in the [build system documentation](../local-dev/cli-build-system#linting). To migrate the ESLint configuration of all packages in your project, run the following command: From 7efe6e84cb8bfcc2c65243d967c480c8424d3ab4 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 8 Mar 2022 14:11:57 +0100 Subject: [PATCH 05/15] docs: update build system docs to use roles Signed-off-by: Patrik Oldsberg --- docs/local-dev/cli-build-system.md | 35 ++++++++++++++---------------- 1 file changed, 16 insertions(+), 19 deletions(-) diff --git a/docs/local-dev/cli-build-system.md b/docs/local-dev/cli-build-system.md index 4b8d2410dc..91767d3b60 100644 --- a/docs/local-dev/cli-build-system.md +++ b/docs/local-dev/cli-build-system.md @@ -243,11 +243,8 @@ nevertheless be useful to know how it works, since all of the published Backstage packages are built using this process. The build is currently using [Rollup](https://rollupjs.org/) and executes in -isolation for each individual package. There are currently three different -commands in the Backstage CLI that invokes the build process, `plugin:build`, -`backend:build`, and simply `build`. The two former are pre-configured commands -for frontend and backend plugins, while the `build` command provides more -control over the output. +isolation for each individual package. The build is invoked using the `package build` +command, and applies to all packages roles except the bundled ones, `frontend` and `backend`. There are three different possible outputs of the build process: JavaScript in CommonJS module format, JavaScript in ECMAScript module format, and type @@ -281,11 +278,11 @@ cover each combination of these cases separately. ### Frontend Development -There are two different commands that start the frontend development bundling: -`app:serve`, which serves an app and uses `src/index` as the entrypoint, and -`plugin:serve`, which serves a plugin and uses `dev/index` as the entrypoint. -These are typically invoked via the `yarn start` script, and are intended for -local development only. When running the bundle command, a development server +The frontend development setup is used for all packages with a frontend role, and +is invoked using the `package start` command. +The only difference between the different roles is that packages with the `'frontend'` +role use `src/index` as the entrypoint, while other roles instead use `dev/index`. +When running the start command, a development server will be set up that listens to the protocol, host and port set by `app.baseUrl` in the configuration. If needed it is also possible to override the listening options through the `app.listen` configuration. @@ -309,8 +306,8 @@ support for them instead. ### Frontend Production The frontend production bundling creates your typical web content bundle, all -contained within a single folder, ready for static serving. It is invoked using -the `app:build` command, and unlike the development bundling there is no way to +contained within a single folder, ready for static serving. It is used when building +packages with the `'frontend'` role, and unlike the development bundling there is no way to build a production bundle of an individual plugin. The output of the bundling process is written to the `dist` folder in the package. @@ -405,7 +402,7 @@ dependencies installed, and as soon as you copy over and extract the contents of the `bundle.tar.gz` archive on top of it, the backend will be ready to run. The following is an example of a `Dockerfile` that can be used to package the -output of `backstage-cli backend:bundle` into an image: +output of building a package with role `'backend'` into an image: ```Dockerfile FROM node:16-bullseye-slim @@ -617,12 +614,12 @@ The following is an excerpt of a typical setup of an isomorphic library package: "types": "dist/index.d.ts" }, "scripts": { - "build": "backstage-cli build", - "lint": "backstage-cli lint", - "test": "backstage-cli test", - "prepack": "backstage-cli prepack", - "postpack": "backstage-cli postpack", - "clean": "backstage-cli clean" + "build": "backstage-cli package build", + "lint": "backstage-cli package lint", + "test": "backstage-cli package test", + "clean": "backstage-cli package clean", + "prepack": "backstage-cli package prepack", + "postpack": "backstage-cli package postpack" }, "files": ["dist"], ``` From d2ecde959b9f4d550b6b10adb821ecc36bf0821b Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 8 Mar 2022 14:17:04 +0100 Subject: [PATCH 06/15] cli: mark package role command categories as stable Signed-off-by: Patrik Oldsberg --- .changeset/pretty-vans-unite.md | 5 +++++ packages/cli/src/commands/index.ts | 24 ++++++++---------------- 2 files changed, 13 insertions(+), 16 deletions(-) create mode 100644 .changeset/pretty-vans-unite.md diff --git a/.changeset/pretty-vans-unite.md b/.changeset/pretty-vans-unite.md new file mode 100644 index 0000000000..6efb6a57ec --- /dev/null +++ b/.changeset/pretty-vans-unite.md @@ -0,0 +1,5 @@ +--- +'@backstage/cli': patch +--- + +The new `package`, `repo`, and `migrate` command categories are now marked as stable. These are tied to the use of package roles, which we now encourage you to use. Please check out the [migration guide](https://backstage.io/docs/tutorials/package-role-migration). diff --git a/packages/cli/src/commands/index.ts b/packages/cli/src/commands/index.ts index a79f9fe81b..9b272fab95 100644 --- a/packages/cli/src/commands/index.ts +++ b/packages/cli/src/commands/index.ts @@ -27,10 +27,8 @@ const configOption = [ export function registerRepoCommand(program: CommanderStatic) { const command = program - .command('repo [command]', { hidden: true }) - .description( - 'Command that run across an entire Backstage project [EXPERIMENTAL]', - ); + .command('repo [command]') + .description('Command that run across an entire Backstage project'); command .command('build') @@ -65,17 +63,14 @@ export function registerRepoCommand(program: CommanderStatic) { export function registerScriptCommand(program: CommanderStatic) { const command = program - .command('package [command]', { hidden: true }) - .description('Lifecycle scripts for individual packages [EXPERIMENTAL]'); + .command('package [command]') + .description('Lifecycle scripts for individual packages'); command .command('start') .description('Start a package for local development') .option(...configOption) - .option( - '--role ', - 'Run the command with an explicit package role [EXPERIMENTAL]', - ) + .option('--role ', 'Run the command with an explicit package role') .option('--check', 'Enable type checking and linting if available') .option('--inspect', 'Enable debugger in Node.js environments') .option( @@ -87,10 +82,7 @@ export function registerScriptCommand(program: CommanderStatic) { command .command('build') .description('Build a package for production deployment or publishing') - .option( - '--role ', - 'Run the command with an explicit package role [EXPERIMENTAL]', - ) + .option('--role ', 'Run the command with an explicit package role') .option( '--minify', 'Minify the generated code. Does not apply to app or backend packages.', @@ -151,8 +143,8 @@ export function registerScriptCommand(program: CommanderStatic) { export function registerMigrateCommand(program: CommanderStatic) { const command = program - .command('migrate [command]', { hidden: true }) - .description('Migration utilities [EXPERIMENTAL]'); + .command('migrate [command]') + .description('Migration utilities'); command .command('package-roles') From 567b14a27b2a52ebf59a357de95a9a5b1d4be5c0 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 8 Mar 2022 14:52:57 +0100 Subject: [PATCH 07/15] docs: update cli command docs Signed-off-by: Patrik Oldsberg --- docs/local-dev/cli-build-system.md | 16 +- docs/local-dev/cli-commands.md | 583 ++++++++--------------------- 2 files changed, 164 insertions(+), 435 deletions(-) diff --git a/docs/local-dev/cli-build-system.md b/docs/local-dev/cli-build-system.md index 91767d3b60..a850673090 100644 --- a/docs/local-dev/cli-build-system.md +++ b/docs/local-dev/cli-build-system.md @@ -326,13 +326,25 @@ correctly from linked in packages, the `ModuleScopePlugin` from [`react-dev-utils`](https://www.npmjs.com/package/react-dev-utils) which makes sure that imports don't reach outside the package, a few fallbacks for some Node.js modules like `'buffer'` and `'events'`, a plugin that writes the -frontend configuration to the bundle as `process.env.APP_CONFIG` and build -information as `process.env.BUILD_INFO`, and lastly minification handled by +frontend configuration to the bundle as `process.env.APP_CONFIG`, and lastly minification handled by [esbuild](https://esbuild.github.io/) using the [`esbuild-loader`](https://npm.im/esbuild-loader). There are of course also a set of loaders configured, which you can read more about in the [loaders](#loaders) and [transpilation](#transpilation) sections. +During the build, the following constants are also set: + +```java +process.env.NODE_ENV = 'production'; +process.env.BUILD_INFO = { + cliVersion: '0.4.0', // The version of the CLI package + gitVersion: 'v0.4.0-86-ge54815618', // output of `git describe --always` + packageVersion: '1.0.5', // The version of the app package itself + timestamp: 1678900000000, // Date.now() when the build started + commit: 'e548156182a973ed4b459e18533afc22c85ffff8', // output of `git rev-parse HEAD` +}; +``` + The output of the bundling process is split into two categories of files with separate caching strategies. The first is a set of generic assets with plain names in the root of the `dist/` folder. You will want to serve these with diff --git a/docs/local-dev/cli-commands.md b/docs/local-dev/cli-commands.md index eff6404e3b..78c311e5cf 100644 --- a/docs/local-dev/cli-commands.md +++ b/docs/local-dev/cli-commands.md @@ -7,251 +7,202 @@ description: Descriptions of all commands available in the CLI. This page lists all commands provided by the Backstage CLI, what they're for, and where to use them. -The documentation for each command begins with specifying its scope, this -indicates where the command should be used by selecting from the following list: - -- `app` - A frontend app package, such as `packages/app`. -- `backend` - A backend package, such as `packages/backend`. -- `frontend-plugin` - A frontend plugin package. -- `backend-plugin` - A backend plugin package. -- `root` - The monorepo root. -- `any` - Any kind of package, but not the repo root. - ## help This command displays a help summary or detailed help screens for each command. -Below is a cleaned up output of `yarn backstage-cli --help`. +Below is a cleaned up output of `yarn backstage-cli --help` ```text -app:build Build an app for a production release -app:serve Serve an app for local development +repo [command] Command that run across an entire Backstage project +package [command] Lifecycle scripts for individual packages +migrate [command] Migration utilities -backend:build Build a backend plugin -backend:bundle Bundle the backend into a deployment archive -backend:build-image Bundles the package into a docker image -backend:dev Start local development server with HMR for the backend +create Open up an interactive guide to creating new things in your app -plugin:build Build a plugin -plugin:diff Diff an existing plugin with the creation template -plugin:serve Serves the dev/ folder of a plugin +config:docs Browse the configuration reference documentation +config:print Print the app configuration for the current package +config:check Validate that the given configuration loads and matches schema +config:schema Dump the app configuration schema -build Build a package for publishing -build-workspace Builds a temporary dist workspace from the provided packages -lint Lint a package -test Run tests, forwarding args to Jest, defaulting to watch mode -clean Delete cache directories +versions:bump Bump Backstage packages to the latest versions +versions:check Check Backstage package versioning -create Open up an interactive guide to creating new things in your app -create-plugin Creates a new plugin in the current repository -remove-plugin Removes plugin in the current repository +build-workspace Builds a temporary dist workspace from the provided packages +create-github-app Create new GitHub App in your organization (experimental) -config:docs Browse the configuration reference documentation -config:print Print the app configuration for the current package -config:check Validate that the given configuration loads and matches schema -config:schema Dump the app configuration schema - -versions:bump Bump Backstage packages to the latest versions -versions:check Check Backstage package versioning - -prepack Prepares a package for packaging before publishing -postpack Restores the changes made by the prepack command - -create-github-app Create new GitHub App in your organization (experimental) - -info Show helpful information for debugging and reporting bugs -help [command] display help for command +info Show helpful information for debugging and reporting bugs +help [command] display help for command ``` -## app:build - -Scope: `app` - -Builds a bundle of static content from the app, which can then be served via any -static web server such as `nginx`, or via the -[`app-backend`](https://www.npmjs.com/package/@backstage/plugin-app-backend) -plugin directly from a Backstage backend instance. - -The command also reads and injects static configuration into the bundle. It is -important to note that when deploying using your own static content hosting -solution, this will be the final configuration used in the frontend unless you -for example hook in configuration loading from the backend. When using the -`nginx` based Dockerfile in this repo along with its included run script, -`APP_CONFIG_` environment variables will be injected into the frontend, and when -serving using the `app-backend` plugin, the configuration is completely injected -from the backend and the configuration at the time of calling this command will -not be used. - -Note that even when injecting configuration at runtime, it is not possible to -change the base path of the app. For example, if you at build time have -`app.baseUrl` set to `http://dev-app.com/my-app`, you can change that to -`https://prod-app.com/my-app`, but not to `https://prod-app.com`, as that would -change the path. - -During the build, the following variables are set: - -```java -process.env.NODE_ENV = 'production'; -process.env.BUILD_INFO = { - cliVersion: '0.4.0', // The version of the CLI package - gitVersion: 'v0.4.0-86-ge54815618', // output of `git describe --always` - packageVersion: '1.0.5', // The version of the app package itself - timestamp: 1678900000000, // Date.now() when the build started - commit: 'e548156182a973ed4b459e18533afc22c85ffff8', // output of `git rev-parse HEAD` -}; -``` - -Some CI environments do not properly report correct resource limits, potentially -leading to errors such as `ENOMEM` during compilation. If you run into this -issue you can limit the parallelization of the build process by setting the -environment variable `BACKSTAGE_CLI_BUILD_PARALLEL`, which is forwarded to the -[`terser-webpack-plugin`](https://github.com/webpack-contrib/terser-webpack-plugin#parallel). -You can set it to `false` or `1` to completely disable parallelization, but -usually a low value such as `2` is enough. +The `package` command category, `yarn backstage-cli package --help` ```text -Usage: backstage-cli app:build +start [options] Start a package for local development +build [options] Build a package for production deployment or publishing +lint [options] Lint a package +test Run tests, forwarding args to Jest, defaulting to watch mode +clean Delete cache directories +prepack Prepares a package for packaging before publishing +postpack Restores the changes made by the prepack command +``` + +The `repo` command category, `yarn backstage-cli repo --help` + +```text +build [options] Build packages in the project, excluding bundled app and backend packages. +lint [options] Lint all packages in the project +``` + +The `migrate` command category, `yarn backstage-cli migrate --help` + +```text +package-roles Add package role field to packages that don't have it +package-scripts Set package scripts according to each package role +package-lint-configs Migrates all packages to use @backstage/cli/config/eslint-factory +``` + +## repo build + +Builds all packages in the project, excluding bundled packages by default, i.e. ones +with the role `'frontend'` or `'backend'`. + +```text +Usage: backstage-cli repo build [options] + +Build packages in the project, excluding bundled app and backend packages. + +Options: + --all Build all packages, including bundled app and backend packages. + --since <ref> Only build packages and their dev dependents that changed since the specified ref +``` + +## repo lint + +Lint all packages in the project. + +```text +Usage: backstage-cli repo lint [options] + +Lint all packages in the project + +Options: + --format <format> Lint report output format (default: "eslint-formatter-friendly") + --since <ref> Only lint packages that changed since the specified ref + --fix Attempt to automatically fix violations +``` + +## package start + +Starts the package for local development. See the frontend and backend development parts in the build system [bundling](./cli-build-system#bundling) section for more details. + +```text +Usage: backstage-cli package start [options] + +Start a package for local development Options: - --stats Write bundle stats to output directory - --lax Do not require environment variables to be set --config <path> Config files to load instead of app-config.yaml (default: []) - -h, --help display help for command + --role <name> Run the command with an explicit package role + --check Enable type checking and linting if available + --inspect Enable debugger in Node.js environments + --inspect-brk Enable debugger in Node.js environments, breaking before code starts ``` -## app:serve +## package build -Scope: `app` - -Serve an app for local development. This starts up a local development server, -using a bundling configuration that is quite similar to that of the `app:build` -command, but with development features such as React Hot Module Replacement, -faster sourcemaps, no minification, etc. - -The static configuration is injected into the frontend, but it does not support -watching, meaning that changes in for example `app-config.yaml` are not -reflected until the serve process is restarted. - -During the build, the following variables are set: - -```java -process.env.NODE_ENV = 'development'; -process.env.BUILD_INFO = { /* See app:build */ }; -``` - -The server listening configuration is controlled through the static -configuration. The `app.baseUrl` determines the listening host and port, as well -as whether HTTPS is used or not. It is also possible to override the listening -host and port if needed by setting `app.listen.host` and `app.listen.port`. +Build an individual package based on its role. See the build system [building](./cli-build-system#building) and [bundling](./cli-build-system#bundling) sections for more details. ```text -Usage: backstage-cli app:serve [options] +Usage: backstage-cli package build [options] + +Build a package for production deployment or publishing Options: - --check Enable type checking and linting - --config <path> Config files to load instead of app-config.yaml (default: []) - -h, --help display help for command + --role <name> Run the command with an explicit package role + --minify Minify the generated code. Does not apply to app or backend packages. + --experimental-type-build Enable experimental type build. Does not apply to app or backend packages. + --skip-build-dependencies Skip the automatic building of local dependencies. Applies to backend packages only. + --stats If bundle stats are available, write them to the output directory. Applies to app packages only. + --config <path> Config files to load instead of app-config.yaml. Applies to app packages only. (default: []) ``` -## backend:build +## package lint -Scope: `backend-plugin` - -This builds a backend package for publishing and use in production. The build -output is written to `dist/`. Be sure to list any additional file that the -package depends on at runtime in the `"files"` field inside `package.json`, a -common example being the `migrations` directory. +Lint a package. In addition to the default `eslint` behavior, this command will +include TypeScript files, treat warnings as errors, and default to linting the +entire directory if no specific files are listed. For more information, see the +build system [linting](./cli-build-system.md#linting) section. ```text -Usage: backstage-cli backend:build [options] +Usage: backstage-cli package lint [options] + +Lint a package Options: - --minify Minify the generated code - -h, --help display help for command + --format <format> Lint report output format (default: "eslint-formatter-friendly") + --fix Attempt to automatically fix violations ``` -## backend:bundle +## package test -Scope: `backend` +Run tests, forwarding all unknown options to Jest, and defaulting to watch mode. +When executing the tests, `process.env.NODE_ENV` will be set to `"test"`. -Bundles the backend into a `dist/bundle.tar.gz` archive. See the -[backend bundling](./cli-build-system.md#backend-production-bundling) build -systems documentation for more details. +This command uses a default Jest configuration that is included in the CLI, +which is set up with similar goals for speed, scale, and working within a +monorepo. The configuration sets the `src` as the root directory, enforces the +`.test.` infix for tests, and uses `src/setupTests.ts` as the test setup +location. The included configuration also supports test execution at the root of +a yarn workspaces monorepo by automatically creating one grouped configuration +that includes all packages that have `backstage-cli test` in their package +`test` script. + +For more information about configuration overrides and editor support, see the [Jest Configuration section](./cli-build-system.md#jest-configuration) in the build system documentation. ```text -Usage: backstage-cli backend:bundle [options] +Usage: backstage-cli package test [options] -Bundle the backend into a deployment archive +Run tests, forwarding args to Jest, defaulting to watch mode Options: - --build-dependencies Build all local package dependencies before bundling the backend - -h, --help display help for command -``` - -## backend:build-image - -Scope: `backend` - -Builds a Docker image of the backend package, forwarding all unknown options to -`docker image build`. For example: - -```bash -yarn backstage-cli backend:build-image --build --tag my-backend-image -``` - -The image is built using the backend package along with all of its local package -dependencies. It expects to find a `Dockerfile` at the root of the backend -package, which will be used during the build. - -The Dockerfile is **NOT** executed within the package or repo itself. Because -the packages in the repo itself are configured for development instead of -production use, the final Docker build happens in a separate temporary -directory, to which the backend package and dependencies have been copied. Only -files listed within the `"files"` field within each package's `package.json` are -copied over, along with the root `package.json`, `yarn.lock`, and any -`app-config.*.yaml` files. - -During the build a `skeleton.tar` file is created and put at the repo root. This -file contains the `package.json` of each included package, which together with -the root `package.json` and `yarn.lock` can be used to run a cached -`yarn install` before the full production builds of all the packages are copied -over, providing a significant speedup if Docker build layer caching available. - -This command is experimental and we hope to be able to replace it with one that -is less integrated directly with Docker, and also supports multi-stage Docker -builds. It is possible to replicate most of what this command does by manually -building each package, and then use the `build-workspace` to create the -temporary workspace, and finally copy over any additional files to the workspace -and execute the Docker build within it. - -```text -Usage: backstage-cli backend:build-image [options] - -Options: - --build Build packages before packing them into the image --backstage-cli-help display help for command ``` -## backend:dev +## package clean -Scope: `backend`, `backend-plugin` - -Starts a backend package in development mode, with watch mode enabled for all -local dependencies. +Remove cache and output directories. ```text -Usage: backstage-cli backend:dev [options] +Usage: backstage-cli package clean [options] -Options: - --check Enable type checking and linting - --inspect Enable debugger - --config <path> Config files to load instead of app-config.yaml (default: []) - -h, --help display help for command +Delete cache directories +``` + +## package prepack + +This command should be added as `scripts.prepack` in all packages. It enables +packaging- and publish-time overrides for fields inside `packages.json`. +For more details, see the build system [publishing](./cli-build-system.md#publishing) section. + +```text +Usage: backstage-cli package prepack [options] + +Prepares a package for packaging before publishing +``` + +## package postpack + +This should be added as `scripts.postpack` in all packages. It restores +`package.json` to what it looked like before calling the `prepack` command. + +```text +Usage: backstage-cli package postpack [options] + +Restores the changes made by the prepack command ``` ## create -Scope: `root` - The `create` command opens up an interactive guide for you to create new things in your app. If you do not pass in any options it is completely interactive, but it is possible to pre-select what you want to create using the `--select` flag, @@ -278,181 +229,16 @@ this: Usage: backstage-cli create [options] Options: - --select Select the thing you want to be creating upfront - --option = Pre-fill options for the creation process (default: []) - --scope The scope to use for new packages - --npm-registry The package registry to use for new packages + --select <name> Select the thing you want to be creating upfront + --option <name>=<value> Pre-fill options for the creation process (default: []) + --scope <scope> The scope to use for new packages + --npm-registry <URL> The package registry to use for new packages --no-private Do not mark new packages as private -h, --help display help for command ``` -## create-plugin - -Scope: `root` - -Creates a new plugin within the repository. This command is typically wrapped up -in the root `package.json` to be executed with `yarn create-plugin`, using -options that are appropriate for the organization that owns the app repo. A -recommended scope for internal packages is `@internal`. - -```text -Usage: backstage-cli create-plugin [options] - -Options: - --backend Create plugin with the backend dependencies as default - --scope <scope> npm scope - --npm-registry <URL> npm registry URL - --no-private Public npm package - -h, --help display help for command -``` - -## remove-plugin - -Scope: `root` - -A utility to remove a plugin from a repo, essentially undoing everything that -was done by `create-plugin`. - -This is primarily intended as a utility for manual tests and end to end testing -scripts. - -```text -Usage: backstage-cli remove-plugin [options] - -Options: - -h, --help display help for command -``` - -## plugin:build - -Scope: `frontend-plugin` - -Build a frontend plugin for publishing to a package registry. There is no need -to run this command during development or even in CI unless the package is being -published. The `app:bundle` command does not use the output for this command -when bundling local package dependencies. - -The output is written to a `dist/` folder. It also outputs type declarations for -the plugin, and therefore requires `yarn tsc` to have been run first. The input -type declarations are expected to be found within `dist-types/` at the root of -the monorepo. - -```text -Usage: backstage-cli plugin:build [options] - -Options: - --minify Minify the generated code - -h, --help display help for command -``` - -## plugin:serve - -Scope: `frontend-plugin` - -Serves a frontend plugin by itself for isolated development. The serve task -itself is essentially identical to `app:serve`, but the entrypoint is instead -set to the `dev/` folder within the plugin. - -The `dev/` folder typically contains a small wrapper script that hooks up any -necessary mock APIs or other things that are needed for the plugin to function. -The `@backstage/dev-utils` package provides utilities to that end. - -```text -Usage: backstage-cli plugin:serve [options] - -Options: - --check Enable type checking and linting - --config <path> Config files to load instead of app-config.yaml (default: []) - -h, --help display help for command -``` - -## plugin:diff - -Scope: `frontend-plugin` - -Compares a frontend plugin to the `create-plugin` template, making sure that it -hasn't diverged from the template and recommending updates when it has. A good -practice is to run this command after updating the version of the CLI in a -project. - -```text -Usage: backstage-cli plugin:diff [options] - -Options: - --check Fail if changes are required - --yes Apply all changes - -h, --help display help for command -``` - -## build - -Scope: `any` - -Build a single package for publishing, just like the `plugin:build` and -`backend:build` commands. This command is intended for standalone packages that -aren't plugins, and for example support building of isomorphic packages for -usage in both the frontend and backend. - -For frontend packages you'll want to include `esm` output, and for backend -packages `cjs`. Whether to include `types` depends on if you need type -declarations for the package, and also requires `yarn tsc` to have been run -first. - -```text -Usage: backstage-cli build [options] - -Options: - --outputs <formats> List of formats to output [types,cjs,esm] - --minify Minify the generated code - -h, --help display help for command -``` - -## lint - -Scope: `any` - -Lint a package. In addition to the default `eslint` behavior, this command will -include TypeScript files, treat warnings as errors, and default to linting the -entire directory if no specific files are listed. - -```text -Usage: backstage-cli lint [options] - -Options: - --format <format> Lint report output format (default: "eslint-formatter-friendly") - --fix Attempt to automatically fix violations - -h, --help display help for command -``` - -## test - -Scope: `any` - -Run tests, forwarding all unknown options to Jest, and defaulting to watch mode. -When executing the tests, `process.env.NODE_ENV` will be set to `"test"`. - -This command uses a default Jest configuration that is included in the CLI, -which is set up with similar goals for speed, scale, and working within a -monorepo. The configuration sets the `src` as the root directory, enforces the -`.test.` infix for tests, and uses `src/setupTests.ts` as the test setup -location. The included configuration also supports test execution at the root of -a yarn workspaces monorepo by automatically creating one grouped configuration -that includes all packages that have `backstage-cli test` in their package -`test` script. - -For more information about configuration overrides and editor support, see the [Jest Configuration section](./cli-build-system.md#jest-configuration) in the build system documentation. - -```text -Usage: backstage-cli test [options] - -Options: - --backstage-cli-help display help for command -``` - ## config:docs -Scope: `root` - This commands opens up the reference documentation of your apps local configuration schema in the browser. This is useful to get an overview of what configuration values are available to use, a description of what they do and @@ -464,14 +250,12 @@ Usage: backstage-cli config:docs [options] Browse the configuration reference documentation Options: - --package Only include the schema that applies to the given package + --package <name> Only include the schema that applies to the given package -h, --help display help for command ``` ## config:print -Scope: `root` - Print the static configuration, defaulting to reading `app-config.yaml` in the repo root, using schema collected from all local packages in the repo. @@ -497,8 +281,6 @@ Options: ## config:check -Scope: `root` - Validate that static configuration loads and matches schema, defaulting to reading `app-config.yaml` in the repo root and using schema collected from all local packages in the repo. @@ -517,8 +299,6 @@ Options: ## config:schema -Scope: `root` - Dump the configuration schema that was collected from all local packages in the repo. @@ -538,8 +318,6 @@ Options: ## versions:bump -Scope: `root` - Bump all `@backstage` packages to the latest versions. This checks for updates in the package registry, and will update entries both in `yarn.lock` and `package.json` files when necessary. @@ -554,8 +332,6 @@ Options: ## versions:check -Scope: `root` - Validate `@backstage` dependencies within the repo, making sure that there are no duplicates of packages that might lead to breakages. @@ -571,63 +347,8 @@ Options: -h, --help display help for command ``` -## prepack - -Scope: `any` - -This command should be added as `scripts.prepack` in all packages. It enables -packaging- and publish-time overrides for fields inside `packages.json`. - -The checked in version of all packages in a Backstage monorepo are tailored for -local development, and as such `main` and similar fields inside `package.json` -point to development source, i.e. `src/index.ts`. Using this when publishing -would lead to a broken package, since `src/` is not included in the published -package and we instead need to point to files in the `dist/` directory. This -command allows for those fields to be rewritten when needed, and does so by -copying all fields within `publishConfig` to the top-level of each -`package.json`, skipping `access`, `registry`, and `tag`. - -The need for this command may be removed in the future, as this exact method of -overriding fields for publishing is already supported by some package managers. - -```text -Usage: backstage-cli prepack [options] - -Options: - -h, --help display help for command -``` - -## postpack - -Scope: `any` - -This should be added as `scripts.postpack` in all packages. It restores -`package.json` to what it looked like before calling the `prepack` command. - -```text -Usage: backstage-cli postpack [options] - -Options: - -h, --help display help for command -``` - -## clean - -Scope: `any` - -Remove cache and output directories. - -```text -Usage: backstage-cli clean [options] - -Options: - -h, --help display help for command -``` - ## build-workspace -Scope: `any`, `root` - Builds a mirror of the workspace using the packaged production version of each package. This essentially calls `yarn pack` in each included package and unpacks the resulting archive in the target `workspace-dir`. @@ -638,8 +359,6 @@ Usage: backstage-cli build-workspace [options] <workspace-dir> ## create-github-app -Scope: `root` - Creates a GitHub App in your GitHub organization. This is an alternative to token-based [GitHub integration](../integrations/github/locations.md). See [GitHub Apps for Backstage Authentication](../plugins/github-apps.md). @@ -653,8 +372,6 @@ Usage: backstage-cli create-github-app <github-org> ## info -Scope: `root` - Outputs debug information which is useful when opening an issue. Outputs system information, node.js and npm versions, CLI version and type (inside backstage repo or a created app), all `@backstage/*` package dependency versions. From 5f07ecbc8afbef5a83c15dec06dcf04cdeb3d8f9 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 8 Mar 2022 14:54:29 +0100 Subject: [PATCH 08/15] docs: add "package role" to CLI glossary Signed-off-by: Patrik Oldsberg --- docs/local-dev/cli-overview.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/local-dev/cli-overview.md b/docs/local-dev/cli-overview.md index 9e6884aab0..3312926068 100644 --- a/docs/local-dev/cli-overview.md +++ b/docs/local-dev/cli-overview.md @@ -50,3 +50,4 @@ improve the tooling, as well as to more easily keep the system up to date. - **Bundle** - A collection of the deployment artifacts. The output of the bundling process, which brings a collection of packages into a single collection of deployment artifacts. +- **Package Role** - The declared role of a package, see [package roles](./cli-build-system#package-roles). From cd5172a1fb81a73930b5adbac8ed76d2c7a7ce01 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 8 Mar 2022 15:19:32 +0100 Subject: [PATCH 09/15] cli: update templates to use package roles Signed-off-by: Patrik Oldsberg --- .changeset/pretty-vans-unite.md | 6 +++++- .../default-backend-plugin/.eslintrc.js | 4 +--- .../default-backend-plugin/package.json.hbs | 17 ++++++++++------- .../default-common-plugin-package/.eslintrc.js | 4 +--- .../package.json.hbs | 15 +++++++++------ .../cli/templates/default-plugin/.eslintrc.js | 4 +--- .../templates/default-plugin/package.json.hbs | 18 ++++++++++-------- .../templates/scaffolder-module/.eslintrc.js | 4 +--- .../scaffolder-module/package.json.hbs | 16 ++++++++++------ 9 files changed, 48 insertions(+), 40 deletions(-) diff --git a/.changeset/pretty-vans-unite.md b/.changeset/pretty-vans-unite.md index 6efb6a57ec..faf535c053 100644 --- a/.changeset/pretty-vans-unite.md +++ b/.changeset/pretty-vans-unite.md @@ -2,4 +2,8 @@ '@backstage/cli': patch --- -The new `package`, `repo`, and `migrate` command categories are now marked as stable. These are tied to the use of package roles, which we now encourage you to use. Please check out the [migration guide](https://backstage.io/docs/tutorials/package-role-migration). +Package roles are now marked as stable and migration is encouraged. Please check out the [migration guide](https://backstage.io/docs/tutorials/package-role-migration). + +The new `package`, `repo`, and `migrate` command categories are now marked as stable. + +The package templates used by the `create` command have all been updated to use package roles. diff --git a/packages/cli/templates/default-backend-plugin/.eslintrc.js b/packages/cli/templates/default-backend-plugin/.eslintrc.js index 16a033dbc6..e2a53a6ad2 100644 --- a/packages/cli/templates/default-backend-plugin/.eslintrc.js +++ b/packages/cli/templates/default-backend-plugin/.eslintrc.js @@ -1,3 +1 @@ -module.exports = { - extends: [require.resolve('@backstage/cli/config/eslint.backend')], -}; +module.exports = require('@backstage/cli/config/eslint-factory')(__dirname); diff --git a/packages/cli/templates/default-backend-plugin/package.json.hbs b/packages/cli/templates/default-backend-plugin/package.json.hbs index 321ca9c546..dacc1d601a 100644 --- a/packages/cli/templates/default-backend-plugin/package.json.hbs +++ b/packages/cli/templates/default-backend-plugin/package.json.hbs @@ -15,14 +15,17 @@ "main": "dist/index.cjs.js", "types": "dist/index.d.ts" }, + "backstage": { + "role": "backend-plugin" + }, "scripts": { - "start": "backstage-cli backend:dev", - "build": "backstage-cli backend:build", - "lint": "backstage-cli lint", - "test": "backstage-cli test", - "prepack": "backstage-cli prepack", - "postpack": "backstage-cli postpack", - "clean": "backstage-cli clean" + "start": "backstage-cli package start", + "build": "backstage-cli package build", + "lint": "backstage-cli package lint", + "test": "backstage-cli package test", + "clean": "backstage-cli package clean", + "prepack": "backstage-cli package prepack", + "postpack": "backstage-cli package postpack" }, "dependencies": { "@backstage/backend-common": "{{versionQuery '@backstage/backend-common'}}", diff --git a/packages/cli/templates/default-common-plugin-package/.eslintrc.js b/packages/cli/templates/default-common-plugin-package/.eslintrc.js index 13573efa9c..e2a53a6ad2 100644 --- a/packages/cli/templates/default-common-plugin-package/.eslintrc.js +++ b/packages/cli/templates/default-common-plugin-package/.eslintrc.js @@ -1,3 +1 @@ -module.exports = { - extends: [require.resolve('@backstage/cli/config/eslint')], -}; +module.exports = require('@backstage/cli/config/eslint-factory')(__dirname); diff --git a/packages/cli/templates/default-common-plugin-package/package.json.hbs b/packages/cli/templates/default-common-plugin-package/package.json.hbs index efaee496e7..844a951d05 100644 --- a/packages/cli/templates/default-common-plugin-package/package.json.hbs +++ b/packages/cli/templates/default-common-plugin-package/package.json.hbs @@ -17,13 +17,16 @@ "module": "dist/index.esm.js", "types": "dist/index.d.ts" }, + "backstage": { + "role": "common-library" + }, "scripts": { - "build": "backstage-cli build", - "lint": "backstage-cli lint", - "test": "backstage-cli test", - "prepack": "backstage-cli prepack", - "postpack": "backstage-cli postpack", - "clean": "backstage-cli clean" + "build": "backstage-cli package build", + "lint": "backstage-cli package lint", + "test": "backstage-cli package test", + "clean": "backstage-cli package clean", + "prepack": "backstage-cli package prepack", + "postpack": "backstage-cli package postpack" }, "devDependencies": { "@backstage/cli": "{{versionQuery '@backstage/cli'}}" diff --git a/packages/cli/templates/default-plugin/.eslintrc.js b/packages/cli/templates/default-plugin/.eslintrc.js index 13573efa9c..e2a53a6ad2 100644 --- a/packages/cli/templates/default-plugin/.eslintrc.js +++ b/packages/cli/templates/default-plugin/.eslintrc.js @@ -1,3 +1 @@ -module.exports = { - extends: [require.resolve('@backstage/cli/config/eslint')], -}; +module.exports = require('@backstage/cli/config/eslint-factory')(__dirname); diff --git a/packages/cli/templates/default-plugin/package.json.hbs b/packages/cli/templates/default-plugin/package.json.hbs index d38a31fa7d..f7985b497e 100644 --- a/packages/cli/templates/default-plugin/package.json.hbs +++ b/packages/cli/templates/default-plugin/package.json.hbs @@ -15,15 +15,17 @@ "main": "dist/index.esm.js", "types": "dist/index.d.ts" }, + "backstage": { + "role": "frontend-plugin" + }, "scripts": { - "build": "backstage-cli plugin:build", - "start": "backstage-cli plugin:serve", - "lint": "backstage-cli lint", - "test": "backstage-cli test", - "diff": "backstage-cli plugin:diff", - "prepack": "backstage-cli prepack", - "postpack": "backstage-cli postpack", - "clean": "backstage-cli clean" + "start": "backstage-cli package start", + "build": "backstage-cli package build", + "lint": "backstage-cli package lint", + "test": "backstage-cli package test", + "clean": "backstage-cli package clean", + "prepack": "backstage-cli package prepack", + "postpack": "backstage-cli package postpack" }, "dependencies": { "@backstage/core-components": "{{versionQuery '@backstage/core-components'}}", diff --git a/packages/cli/templates/scaffolder-module/.eslintrc.js b/packages/cli/templates/scaffolder-module/.eslintrc.js index 16a033dbc6..e2a53a6ad2 100644 --- a/packages/cli/templates/scaffolder-module/.eslintrc.js +++ b/packages/cli/templates/scaffolder-module/.eslintrc.js @@ -1,3 +1 @@ -module.exports = { - extends: [require.resolve('@backstage/cli/config/eslint.backend')], -}; +module.exports = require('@backstage/cli/config/eslint-factory')(__dirname); diff --git a/packages/cli/templates/scaffolder-module/package.json.hbs b/packages/cli/templates/scaffolder-module/package.json.hbs index de6ffd9e3a..618e953b74 100644 --- a/packages/cli/templates/scaffolder-module/package.json.hbs +++ b/packages/cli/templates/scaffolder-module/package.json.hbs @@ -16,13 +16,17 @@ "main": "dist/index.cjs.js", "types": "dist/index.d.ts" }, + "backstage": { + "role": "backend-plugin-module" + }, "scripts": { - "build": "backstage-cli build --output cjs,types", - "lint": "backstage-cli lint", - "test": "backstage-cli test", - "prepack": "backstage-cli prepack", - "postpack": "backstage-cli postpack", - "clean": "backstage-cli clean" + "start": "backstage-cli package start", + "build": "backstage-cli package build", + "lint": "backstage-cli package lint", + "test": "backstage-cli package test", + "clean": "backstage-cli package clean", + "prepack": "backstage-cli package prepack", + "postpack": "backstage-cli package postpack" }, "dependencies": { "@backstage/plugin-scaffolder-backend": "{{versionQuery '@backstage/plugin-scaffolder-backend'}}" From bde30664c40b391c3918b37521e50acc01b3745a Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 8 Mar 2022 15:22:43 +0100 Subject: [PATCH 10/15] create-app: migrated to use package roles Signed-off-by: Patrik Oldsberg --- .changeset/twenty-birds-think.md | 19 +++++++++++++++++++ packages/app/package.json | 2 +- packages/backend/package.json | 4 ++-- .../templates/default-app/package.json.hbs | 6 +++--- .../default-app/packages/app/.eslintrc.js | 4 +--- .../default-app/packages/app/package.json.hbs | 13 ++++++++----- .../default-app/packages/backend/.eslintrc.js | 4 +--- .../packages/backend/package.json.hbs | 13 ++++++++----- 8 files changed, 43 insertions(+), 22 deletions(-) create mode 100644 .changeset/twenty-birds-think.md diff --git a/.changeset/twenty-birds-think.md b/.changeset/twenty-birds-think.md new file mode 100644 index 0000000000..5b1f9481c0 --- /dev/null +++ b/.changeset/twenty-birds-think.md @@ -0,0 +1,19 @@ +--- +'@backstage/create-app': patch +--- + +Updated template to use package roles. To apply this change to an existing app, check out the [migration guide](https://backstage.io/docs/tutorials/package-role-migration). + +Specifically the following scripts in the root `package.json` have also been updated: + +```diff +- "build": "lerna run build", ++ "build": "backstage-cli repo build --all", + +... + +- "lint": "lerna run lint --since origin/master --", +- "lint:all": "lerna run lint --", ++ "lint": "backstage-cli repo lint --since origin/master", ++ "lint:all": "backstage-cli repo lint", +``` diff --git a/packages/app/package.json b/packages/app/package.json index 45cde6df52..5ae2a1dd08 100644 --- a/packages/app/package.json +++ b/packages/app/package.json @@ -96,9 +96,9 @@ "build": "backstage-cli package build", "clean": "backstage-cli package clean", "test": "backstage-cli package test", + "lint": "backstage-cli package lint", "test:e2e": "start-server-and-test start http://localhost:3000 cy:dev", "test:e2e:ci": "start-server-and-test start http://localhost:3000 cy:run", - "lint": "backstage-cli package lint", "cy:dev": "cypress open", "cy:run": "cypress run" }, diff --git a/packages/backend/package.json b/packages/backend/package.json index b49882b837..dc07124910 100644 --- a/packages/backend/package.json +++ b/packages/backend/package.json @@ -18,12 +18,12 @@ "backstage" ], "scripts": { - "build": "backstage-cli package build", - "build-image": "docker build ../.. -f Dockerfile --tag example-backend", "start": "backstage-cli package start", + "build": "backstage-cli package build", "lint": "backstage-cli package lint", "test": "backstage-cli package test", "clean": "backstage-cli package clean", + "build-image": "docker build ../.. -f Dockerfile --tag example-backend", "migrate:create": "knex migrate:make -x ts" }, "dependencies": { diff --git a/packages/create-app/templates/default-app/package.json.hbs b/packages/create-app/templates/default-app/package.json.hbs index e7c39add25..884eaf23cf 100644 --- a/packages/create-app/templates/default-app/package.json.hbs +++ b/packages/create-app/templates/default-app/package.json.hbs @@ -9,7 +9,7 @@ "dev": "concurrently \"yarn start\" \"yarn start-backend\"", "start": "yarn workspace app start", "start-backend": "yarn workspace backend start", - "build": "lerna run build", + "build": "backstage-cli repo build --all", "build-image": "yarn workspace backend build-image", "tsc": "tsc", "tsc:full": "tsc --skipLibCheck false --incremental false", @@ -17,8 +17,8 @@ "diff": "lerna run diff --", "test": "backstage-cli test", "test:all": "lerna run test -- --coverage", - "lint": "lerna run lint --since origin/master --", - "lint:all": "lerna run lint --", + "lint": "backstage-cli repo lint --since origin/master", + "lint:all": "backstage-cli repo lint", "prettier:check": "prettier --check .", "create-plugin": "backstage-cli create-plugin --scope internal", "remove-plugin": "backstage-cli remove-plugin" diff --git a/packages/create-app/templates/default-app/packages/app/.eslintrc.js b/packages/create-app/templates/default-app/packages/app/.eslintrc.js index 13573efa9c..e2a53a6ad2 100644 --- a/packages/create-app/templates/default-app/packages/app/.eslintrc.js +++ b/packages/create-app/templates/default-app/packages/app/.eslintrc.js @@ -1,3 +1 @@ -module.exports = { - extends: [require.resolve('@backstage/cli/config/eslint')], -}; +module.exports = require('@backstage/cli/config/eslint-factory')(__dirname); diff --git a/packages/create-app/templates/default-app/packages/app/package.json.hbs b/packages/create-app/templates/default-app/packages/app/package.json.hbs index 53e0590db4..71d2ac9b3b 100644 --- a/packages/create-app/templates/default-app/packages/app/package.json.hbs +++ b/packages/create-app/templates/default-app/packages/app/package.json.hbs @@ -3,6 +3,9 @@ "version": "0.0.0", "private": true, "bundled": true, + "backstage": { + "role": "frontend" + }, "dependencies": { "@backstage/app-defaults": "^{{version '@backstage/app-defaults'}}", "@backstage/catalog-model": "^{{version '@backstage/catalog-model'}}", @@ -49,13 +52,13 @@ "start-server-and-test": "^1.10.11" }, "scripts": { - "start": "backstage-cli app:serve", - "build": "backstage-cli app:build", - "clean": "backstage-cli clean", - "test": "backstage-cli test", + "start": "backstage-cli package start", + "build": "backstage-cli package build", + "clean": "backstage-cli package clean", + "test": "backstage-cli package test", + "lint": "backstage-cli package lint", "test:e2e": "cross-env PORT=3001 start-server-and-test start http://localhost:3001 cy:dev", "test:e2e:ci": "cross-env PORT=3001 start-server-and-test start http://localhost:3001 cy:run", - "lint": "backstage-cli lint", "cy:dev": "cypress open", "cy:run": "cypress run" }, diff --git a/packages/create-app/templates/default-app/packages/backend/.eslintrc.js b/packages/create-app/templates/default-app/packages/backend/.eslintrc.js index 16a033dbc6..e2a53a6ad2 100644 --- a/packages/create-app/templates/default-app/packages/backend/.eslintrc.js +++ b/packages/create-app/templates/default-app/packages/backend/.eslintrc.js @@ -1,3 +1 @@ -module.exports = { - extends: [require.resolve('@backstage/cli/config/eslint.backend')], -}; +module.exports = require('@backstage/cli/config/eslint-factory')(__dirname); diff --git a/packages/create-app/templates/default-app/packages/backend/package.json.hbs b/packages/create-app/templates/default-app/packages/backend/package.json.hbs index feba5169ba..79d6772d7e 100644 --- a/packages/create-app/templates/default-app/packages/backend/package.json.hbs +++ b/packages/create-app/templates/default-app/packages/backend/package.json.hbs @@ -4,13 +4,16 @@ "main": "dist/index.cjs.js", "types": "src/index.ts", "private": true, + "backstage": { + "role": "backend" + }, "scripts": { - "build": "backstage-cli backend:bundle", + "start": "backstage-cli package start", + "build": "backstage-cli package build", + "lint": "backstage-cli package lint", + "test": "backstage-cli package test", + "clean": "backstage-cli package clean", "build-image": "docker build ../.. -f Dockerfile --tag backstage", - "start": "backstage-cli backend:dev", - "lint": "backstage-cli lint", - "test": "backstage-cli test", - "clean": "backstage-cli clean", "migrate:create": "knex migrate:make -x ts" }, "dependencies": { From 9d7fc090ac0263ea5440f9e702565f58637b74d0 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 8 Mar 2022 15:35:23 +0100 Subject: [PATCH 11/15] docs: package role migration guide tweaks Signed-off-by: Patrik Oldsberg --- docs/tutorials/package-role-migration.md | 24 ++++++++++-------------- 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/docs/tutorials/package-role-migration.md b/docs/tutorials/package-role-migration.md index d9d9c8c91a..a27dbb2e70 100644 --- a/docs/tutorials/package-role-migration.md +++ b/docs/tutorials/package-role-migration.md @@ -5,27 +5,26 @@ description: Guide for how to migrate packages to use the new role utility --- The Backstage CLI has introduced the concept of package roles, whose purpose is to -enable more powerful tooling and leaner package configuration. More background and -information about the change can be found in the [original RFC](https://github.com/backstage/backstage/issues/8729). +enable more powerful tooling, optimizations, and leaner package configuration. More background and +information about the change can be found in the [original RFC](https://github.com/backstage/backstage/issues/8729) and the [FAQ](#faq) on this page. Package roles are implemented through a well-known `"backstage"."role"` field in the `package.json` of each package. There are a handful of roles defined so far, and it -is not possible to use value outside the set of predefined roles. Some examples of -these roles are `frontend-plugin`, `node-library`, and `backend-plugin-module`. +is not possible to use values outside the [set of predefined roles](../local-dev/cli-build-system#package-roles). With roles in place in all packages, the Backstage CLI is able to automatically determine how to handle each package. For example, the different build commands have been replaced by a single one that instead knows how to build each role. The test and lint configurations are also selected automatically based on the role, and a new category of `repo` commands have been introduced in the CLI, which are able -to operate across all packages at once. +to operate across all packages simultaneously. Package roles have been used in the Backstage main repository for a while, and we now recommend that all Backstage projects are migrated to use package roles. ## Migration -In order to make the migration as smooth as possible, `@backstage/cli` provides +In order to make the migration as smooth as possible `@backstage/cli` provides a number of migration utilities. Using these in combination with some manual review and optional steps should be all you need to migrate to package roles in most projects. @@ -48,24 +47,20 @@ Have a look at the new commands under `yarn backstage-cli repo`, and switch to t ### Step 1 - Add package roles -The first step is to add the `"backstage"."role"` field to each package. This -is done by running the following command: +The first step is to add the `"backstage"."role"` field to each package. This can of course be done manually, but the following command will attempt to automatically detect the role of each package in your project: ```sh yarn backstage-cli migrate package-roles ``` -This will add the role field to each package in your project, detecting the role -based on existing information like what build scripts are in place and the package name. - -This automatic detection is not perfect, so it recommended to manually review the +The 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](../local-dev/cli-build-system#package-roles) as a reference. ### Step 2 - Migrate package scripts The migration to package roles also introduces a new `package` command category to the CLI. -Each command under the `package` category is designed to be mapped directly to an entry in `"scripts"` in `package.json`. These commands replace the existing commands like `build`, `app:build`, `lint` and `test`. They look something like this: +Each command under the `package` category is designed to be mapped directly to an entry in `"scripts"` in `package.json`. These commands replace the existing commands like `build`, `app:build`, `lint`, and `test`. They look something like this: ```json { @@ -102,7 +97,7 @@ This will migrate all existing `.eslintrc.js` that extend the old configuration ### Step 4 - Use `backstage-cli repo` -The Backstage CLI recently introduced a new `repo` command category, which houses commands that operate on an entire monorepo at once. These commands work particularly well once packages have been migrated to use roles, as that allows for some very effective optimizations. It is typically much faster to use these commands compared to using tools like `lerna`, as they're able to avoid the overhead of calling package scripts through `yarn`. You can read more about the `repo` command in the [CLI command documentation](./not-found#TODO). +The Backstage CLI recently introduced a new `repo` command category, which houses commands that operate on an entire monorepo at once. These commands work particularly well once packages have been migrated to use roles, as that allows for some very effective optimizations. It is typically much faster to use these commands compared to using tools like `lerna`, as they're able to avoid the overhead of calling package scripts through `yarn` and can operate on multiple packages at once. You can read more about the `repo` command in the [CLI command documentation](../local-dev/cli-commands#repo-build). The way to execute this step of the migration is not as well defined as the previous steps, as it depends on what your development and CI/CD setup looks like. Look for the following patterns to replace in your root `package.json` as well as CI/CD setup: @@ -132,6 +127,7 @@ To keep configuration lean, allow for more utilities and tooling, and to enable ### Do I have to migrate to using package roles? Short answer - yes. + Longer answer - mostly, you can get around having to declare package the role of your packages by instead explicitly declaring the role in the command invocation or configuration. For example, the `app:build` command will go away, but you can replace it with `package build --role frontend` if you don't want to declare the role in `package.json` . It is however strongly recommended to declare the package roles. ### I have a package where none of the existing roles apply From d082db302b06288359969474b8b81d8c6a857877 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 8 Mar 2022 15:37:49 +0100 Subject: [PATCH 12/15] cli: mark deprecated commands as deprecated Signed-off-by: Patrik Oldsberg --- .changeset/pretty-vans-unite.md | 2 ++ packages/cli/src/commands/index.ts | 34 ++++++++++++++++++------------ 2 files changed, 23 insertions(+), 13 deletions(-) diff --git a/.changeset/pretty-vans-unite.md b/.changeset/pretty-vans-unite.md index faf535c053..318e86d069 100644 --- a/.changeset/pretty-vans-unite.md +++ b/.changeset/pretty-vans-unite.md @@ -6,4 +6,6 @@ Package roles are now marked as stable and migration is encouraged. Please check The new `package`, `repo`, and `migrate` command categories are now marked as stable. +Marked all commands that are being replaced by the new `package` and `repo` commands as deprecated. + The package templates used by the `create` command have all been updated to use package roles. diff --git a/packages/cli/src/commands/index.ts b/packages/cli/src/commands/index.ts index 9b272fab95..bc427bb19b 100644 --- a/packages/cli/src/commands/index.ts +++ b/packages/cli/src/commands/index.ts @@ -172,7 +172,7 @@ export function registerCommands(program: CommanderStatic) { // TODO(Rugvip): Deprecate in favor of package variant program .command('app:build') - .description('Build an app for a production release') + .description('Build an app for a production release [DEPRECATED]') .option('--stats', 'Write bundle stats to output directory') .option(...configOption) .action(lazy(() => import('./app/build').then(m => m.default))); @@ -180,7 +180,7 @@ export function registerCommands(program: CommanderStatic) { // TODO(Rugvip): Deprecate in favor of package variant program .command('app:serve') - .description('Serve an app for local development') + .description('Serve an app for local development [DEPRECATED]') .option('--check', 'Enable type checking and linting') .option(...configOption) .action(lazy(() => import('./app/serve').then(m => m.default))); @@ -188,7 +188,7 @@ export function registerCommands(program: CommanderStatic) { // TODO(Rugvip): Deprecate in favor of package variant program .command('backend:build') - .description('Build a backend plugin') + .description('Build a backend plugin [DEPRECATED]') .option('--minify', 'Minify the generated code') .option('--experimental-type-build', 'Enable experimental type build') .action(lazy(() => import('./backend/build').then(m => m.default))); @@ -196,7 +196,7 @@ export function registerCommands(program: CommanderStatic) { // TODO(Rugvip): Deprecate in favor of package variant program .command('backend:bundle') - .description('Bundle the backend into a deployment archive') + .description('Bundle the backend into a deployment archive [DEPRECATED]') .option( '--build-dependencies', 'Build all local package dependencies before bundling the backend', @@ -206,7 +206,9 @@ export function registerCommands(program: CommanderStatic) { // TODO(Rugvip): Deprecate in favor of package variant program .command('backend:dev') - .description('Start local development server with HMR for the backend') + .description( + 'Start local development server with HMR for the backend [DEPRECATED]', + ) .option('--check', 'Enable type checking and linting') .option('--inspect', 'Enable debugger') .option('--inspect-brk', 'Enable debugger with await to attach debugger') @@ -255,7 +257,7 @@ export function registerCommands(program: CommanderStatic) { // TODO(Rugvip): Deprecate in favor of package variant program .command('plugin:build') - .description('Build a plugin') + .description('Build a plugin [DEPRECATED]') .option('--minify', 'Minify the generated code') .option('--experimental-type-build', 'Enable experimental type build') .action(lazy(() => import('./plugin/build').then(m => m.default))); @@ -263,7 +265,7 @@ export function registerCommands(program: CommanderStatic) { // TODO(Rugvip): Deprecate in favor of package variant program .command('plugin:serve') - .description('Serves the dev/ folder of a plugin') + .description('Serves the dev/ folder of a plugin [DEPRECATED]') .option('--check', 'Enable type checking and linting') .option(...configOption) .action(lazy(() => import('./plugin/serve').then(m => m.default))); @@ -278,7 +280,7 @@ export function registerCommands(program: CommanderStatic) { // TODO(Rugvip): Deprecate in favor of package variant program .command('build') - .description('Build a package for publishing') + .description('Build a package for publishing [DEPRECATED]') .option('--outputs ', 'List of formats to output [types,cjs,esm]') .option('--minify', 'Minify the generated code') .option('--experimental-type-build', 'Enable experimental type build') @@ -293,7 +295,7 @@ export function registerCommands(program: CommanderStatic) { 'eslint-formatter-friendly', ) .option('--fix', 'Attempt to automatically fix violations') - .description('Lint a package') + .description('Lint a package [DEPRECATED]') .action(lazy(() => import('./lint').then(m => m.default))); // TODO(Rugvip): Deprecate in favor of package variant @@ -301,7 +303,9 @@ export function registerCommands(program: CommanderStatic) { .command('test') .allowUnknownOption(true) // Allows the command to run, but we still need to parse raw args .helpOption(', --backstage-cli-help') // Let Jest handle help - .description('Run tests, forwarding args to Jest, defaulting to watch mode') + .description( + 'Run tests, forwarding args to Jest, defaulting to watch mode [DEPRECATED]', + ) .action(lazy(() => import('./testCommand').then(m => m.default))); program @@ -385,19 +389,23 @@ export function registerCommands(program: CommanderStatic) { // TODO(Rugvip): Deprecate in favor of package variant program .command('prepack') - .description('Prepares a package for packaging before publishing') + .description( + 'Prepares a package for packaging before publishing [DEPRECATED]', + ) .action(lazy(() => import('./pack').then(m => m.pre))); // TODO(Rugvip): Deprecate in favor of package variant program .command('postpack') - .description('Restores the changes made by the prepack command') + .description( + 'Restores the changes made by the prepack command [DEPRECATED]', + ) .action(lazy(() => import('./pack').then(m => m.post))); // TODO(Rugvip): Deprecate in favor of package variant program .command('clean') - .description('Delete cache directories') + .description('Delete cache directories [DEPRECATED]') .action(lazy(() => import('./clean/clean').then(m => m.default))); program From 227714a0ef2d2028746835d9f1032ee7265016be Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 8 Mar 2022 15:45:34 +0100 Subject: [PATCH 13/15] docs: update multi-stage docker build to use package role build Signed-off-by: Patrik Oldsberg --- docs/deployment/docker.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/deployment/docker.md b/docs/deployment/docker.md index 36967f352a..0b99e81d64 100644 --- a/docs/deployment/docker.md +++ b/docs/deployment/docker.md @@ -167,7 +167,9 @@ RUN yarn install --frozen-lockfile --network-timeout 600000 && rm -rf "$(yarn ca COPY . . RUN yarn tsc -RUN yarn --cwd packages/backend backstage-cli backend:bundle --build-dependencies +RUN yarn --cwd packages/backend build +# If you have not yet migrated to package roles, use the following command instead: +# RUN yarn --cwd packages/backend backstage-cli backend:bundle --build-dependencies # Stage 3 - Build the actual backend image and install production dependencies FROM node:16-bullseye-slim From 3cdb6c79ba128782efd7d3721931e522c7cca197 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 8 Mar 2022 19:35:14 +0100 Subject: [PATCH 14/15] docs: fix build system doc links Signed-off-by: Patrik Oldsberg --- docs/local-dev/cli-commands.md | 4 ++-- docs/local-dev/cli-overview.md | 2 +- docs/tutorials/package-role-migration.md | 8 ++++---- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/local-dev/cli-commands.md b/docs/local-dev/cli-commands.md index 78c311e5cf..7157fad2bf 100644 --- a/docs/local-dev/cli-commands.md +++ b/docs/local-dev/cli-commands.md @@ -93,7 +93,7 @@ Options: ## package start -Starts the package for local development. See the frontend and backend development parts in the build system [bundling](./cli-build-system#bundling) section for more details. +Starts the package for local development. See the frontend and backend development parts in the build system [bundling](./cli-build-system.md#bundling) section for more details. ```text Usage: backstage-cli package start [options] @@ -110,7 +110,7 @@ Options: ## package build -Build an individual package based on its role. See the build system [building](./cli-build-system#building) and [bundling](./cli-build-system#bundling) sections for more details. +Build an individual package based on its role. See the build system [building](./cli-build-system.md#building) and [bundling](./cli-build-system.md#bundling) sections for more details. ```text Usage: backstage-cli package build [options] diff --git a/docs/local-dev/cli-overview.md b/docs/local-dev/cli-overview.md index 3312926068..74c09d2865 100644 --- a/docs/local-dev/cli-overview.md +++ b/docs/local-dev/cli-overview.md @@ -50,4 +50,4 @@ improve the tooling, as well as to more easily keep the system up to date. - **Bundle** - A collection of the deployment artifacts. The output of the bundling process, which brings a collection of packages into a single collection of deployment artifacts. -- **Package Role** - The declared role of a package, see [package roles](./cli-build-system#package-roles). +- **Package Role** - The declared role of a package, see [package roles](./cli-build-system.md#package-roles). diff --git a/docs/tutorials/package-role-migration.md b/docs/tutorials/package-role-migration.md index a27dbb2e70..6d262e45c3 100644 --- a/docs/tutorials/package-role-migration.md +++ b/docs/tutorials/package-role-migration.md @@ -10,7 +10,7 @@ information about the change can be found in the [original RFC](https://github.c Package roles are implemented through a well-known `"backstage"."role"` field in the `package.json` of each package. There are a handful of roles defined so far, and it -is not possible to use values outside the [set of predefined roles](../local-dev/cli-build-system#package-roles). +is not possible to use values outside the [set of predefined roles](../local-dev/cli-build-system.md#package-roles). With roles in place in all packages, the Backstage CLI is able to automatically determine how to handle each package. For example, the different build commands @@ -55,7 +55,7 @@ yarn backstage-cli migrate package-roles The 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](../local-dev/cli-build-system#package-roles) as a reference. +You can use the [package role definitions](../local-dev/cli-build-system.md#package-roles) as a reference. ### Step 2 - Migrate package scripts @@ -85,7 +85,7 @@ If you in the end do not want to use this exact script setup, it is still recomm ### Step 3 - Migrate package ESLint configurations -An area that has been simplified as part of the move to package roles is the ESLint configuration. Rather than having each package select which configuration they want (and getting it wrong), they now use a shared configuration factory that utilizes the package role. You can read more about the new configuration setup in the [build system documentation](../local-dev/cli-build-system#linting). +An area that has been simplified as part of the move to package roles is the ESLint configuration. Rather than having each package select which configuration they want (and getting it wrong), they now use a shared configuration factory that utilizes the package role. You can read more about the new configuration setup in the [build system documentation](../local-dev/cli-build-system.md#linting). To migrate the ESLint configuration of all packages in your project, run the following command: @@ -97,7 +97,7 @@ This will migrate all existing `.eslintrc.js` that extend the old configuration ### Step 4 - Use `backstage-cli repo` -The Backstage CLI recently introduced a new `repo` command category, which houses commands that operate on an entire monorepo at once. These commands work particularly well once packages have been migrated to use roles, as that allows for some very effective optimizations. It is typically much faster to use these commands compared to using tools like `lerna`, as they're able to avoid the overhead of calling package scripts through `yarn` and can operate on multiple packages at once. You can read more about the `repo` command in the [CLI command documentation](../local-dev/cli-commands#repo-build). +The Backstage CLI recently introduced a new `repo` command category, which houses commands that operate on an entire monorepo at once. These commands work particularly well once packages have been migrated to use roles, as that allows for some very effective optimizations. It is typically much faster to use these commands compared to using tools like `lerna`, as they're able to avoid the overhead of calling package scripts through `yarn` and can operate on multiple packages at once. You can read more about the `repo` command in the [CLI command documentation](../local-dev/cli-commands.md#repo-build). The way to execute this step of the migration is not as well defined as the previous steps, as it depends on what your development and CI/CD setup looks like. Look for the following patterns to replace in your root `package.json` as well as CI/CD setup: From ea22c04a4ff1bd24e259a2358bb813b0d50fb5ac Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 8 Mar 2022 19:37:18 +0100 Subject: [PATCH 15/15] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Patrik Oldsberg Co-authored-by: Fredrik Adelöw --- docs/local-dev/cli-build-system.md | 2 +- docs/tutorials/package-role-migration.md | 16 ++++++++-------- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/local-dev/cli-build-system.md b/docs/local-dev/cli-build-system.md index a850673090..be07a67f22 100644 --- a/docs/local-dev/cli-build-system.md +++ b/docs/local-dev/cli-build-system.md @@ -79,7 +79,7 @@ implemented in a typical Backstage app. 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: +defined in the `package.json` of each package like this: ```json { diff --git a/docs/tutorials/package-role-migration.md b/docs/tutorials/package-role-migration.md index 6d262e45c3..10d6eca586 100644 --- a/docs/tutorials/package-role-migration.md +++ b/docs/tutorials/package-role-migration.md @@ -43,7 +43,7 @@ yarn backstage-cli migrate package-scripts yarn backstage-cli migrate package-lint-configs ``` -Have a look at the new commands under `yarn backstage-cli repo`, and switch to them wherever you can. They tend to be a much faster compared to their `lerna` equivalents. +Have a look at the new commands under `yarn backstage-cli repo`, and switch to them wherever you can. They tend to be much faster compared to their `lerna` equivalents. ### Step 1 - Add package roles @@ -53,7 +53,7 @@ The first step is to add the `"backstage"."role"` field to each package. This ca yarn backstage-cli migrate package-roles ``` -The automatic detection is not perfect, so it recommended to manually review the +The automatic detection is not perfect, so it is recommended to manually review the roles that were assigned to each package. You can use the [package role definitions](../local-dev/cli-build-system.md#package-roles) as a reference. @@ -73,7 +73,7 @@ Each command under the `package` category is designed to be mapped directly to a } ``` -Every package role each has a fixed set of recommended scripts. It is strongly recommended that you use these scripts, as it allows for optimizations in other parts of the CLI. You can migrate to using all of these scripts by running the following command: +Every package role has a fixed set of recommended scripts. It is strongly recommended that you use these scripts, as it allows for optimizations in other parts of the CLI. You can migrate to using all of these scripts by running the following command: ```sh yarn backstage-cli migrate package-scripts @@ -113,14 +113,14 @@ The way to execute this step of the migration is not as well defined as the prev backstage-cli repo lint --since origin/master ``` -- In places where the entire repo is being built, use `yarn backstage-cli repo build`, which also supports the `--since` flag. The migration here is a bit more nuanced as it depends why you are building all packages. - - If you are building all packages to **verify** that you are able to build them, you most likely want `backstage-cli repo build --all`. The `--all` flag signals that bundled packages like `packages/app` and `packages/backend` should be build as well. Pair this up with a `--since` flag in CI to avoid needing to build all packages. +- In places where the entire repo is being built, use `yarn backstage-cli repo build`, which also supports the `--since` flag. The migration here is a bit more nuanced as it depends on why you are building all packages. + - If you are building all packages to **verify** that you are able to build them, you most likely want `backstage-cli repo build --all`. The `--all` flag signals that bundled packages like `packages/app` and `packages/backend` should be built as well. Pair this up with a `--since` flag in CI to avoid needing to build all packages. - If you are building all packages to **publish** them, then `backstage-cli repo build` is enough, as it builds all published packages. - If you are building all packages to **deploy** them, you likely don't want to use the `repo` command at all, simply call `yarn build` in the packages you want to deploy instead. For example, if you are deploying the backend with a docker host build, it's enough to call `yarn build` inside `packages/backend`. ## FAQ -### Why where packages roles introduced? +### Why were package roles introduced? To keep configuration lean, allow for more utilities and tooling, and to enable optimizations in the build system. You can read more about the reasoning in the [original RFC](https://github.com/backstage/backstage/issues/8729). @@ -128,11 +128,11 @@ To keep configuration lean, allow for more utilities and tooling, and to enable Short answer - yes. -Longer answer - mostly, you can get around having to declare package the role of your packages by instead explicitly declaring the role in the command invocation or configuration. For example, the `app:build` command will go away, but you can replace it with `package build --role frontend` if you don't want to declare the role in `package.json` . It is however strongly recommended to declare the package roles. +Longer answer - mostly, you can get around having to declare the role of your packages by instead explicitly declaring the role in the command invocation or configuration. For example, the `app:build` command will go away, but you can replace it with `package build --role frontend` if you don't want to declare the role in `package.json` . It is however strongly recommended to declare the package roles. ### I have a package where none of the existing roles apply -The `web-library`, `node-library` and `common-library` roles are general purpose roles that should cover most use cases. If you feel like none of those roles work for you either, then please open an issue in the [Backstage repo](https://github.com/backstage/backstage) and suggest the addition of a new role. +The `web-library`, `node-library` and `common-library` roles are general purpose roles that should cover most use cases. If you feel like none of those roles work for you, then please open an issue in the [Backstage repo](https://github.com/backstage/backstage) and suggest the addition of a new role. ### Should I include the role in published packages?