diff --git a/docs/cli/commands.md b/docs/cli/commands.md index ef35f0ad8f..8f8cb74ed7 100644 --- a/docs/cli/commands.md +++ b/docs/cli/commands.md @@ -159,8 +159,38 @@ Options: ## backend:build-image -Bundles the package into a docker image. All extra args are forwarded to -`docker image build`. +Builds a Docker image of the backend package and forwards 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 with the backend package along with all of its local package +dependencies. This uses a `Dockerfile` that is expected to exist at the root of +the backend package. The `Dockerfile` will end up being executed from the root +of the monorepo, rather than the backend package itself. + +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 over. +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, 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] @@ -172,7 +202,8 @@ Options: ## backend:dev -Start local development server with HMR for the backend +Starts a backend package in development mode, with watch mode enabled for all +local packages. ```text Usage: backstage-cli backend:dev [options] @@ -186,7 +217,10 @@ Options: ## create-plugin -Creates a new plugin in the current repository +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] @@ -201,7 +235,11 @@ Options: ## remove-plugin -Removes plugin in the current repository +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] @@ -212,7 +250,15 @@ Options: ## plugin:build -Build a 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] @@ -223,7 +269,13 @@ Options: ## plugin:serve -Serves the dev/ folder of a 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] @@ -236,7 +288,10 @@ Options: ## plugin:diff -Diff an existing plugin with the creation template +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] @@ -249,7 +304,15 @@ Options: ## build -Build a package for publishing +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] @@ -261,7 +324,9 @@ Options: ## lint -Lint a package +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 of no specific files are listed. ```text Usage: backstage-cli lint [options] @@ -274,7 +339,7 @@ Options: ## test -Run tests, forwarding args to Jest, defaulting to watch mode +Run tests, forwarding all unknown options to Jest, and defaulting to watch mode. ```text Usage: backstage-cli test [options] @@ -285,7 +350,15 @@ Options: ## config:print -Print the app configuration for the current package +Print the static configuration, defaulting to reading `app-config.yaml` in the +repo root, using schema collected from all local packages in the repo. + +For example, to validate that a given configuration value is visible in the +frontend when building the `my-app` package, you can use the following: + +```bash +yarn backstage-cli config:print --frontend --package my-app +``` ```text Usage: backstage-cli config:print [options] @@ -301,7 +374,9 @@ Options: ## config:check -Validate that the given configuration loads and matches schema +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. ```text Usage: backstage-cli config:check [options] @@ -314,7 +389,9 @@ Options: ## versions:bump -Bump Backstage packages to the latest versions +Bump all `@backstage` packages to the latest versions. This check for updates in +the package registry, and will update entries both in `yarn.lock` and +`package.json` files when necessary. ```text Usage: backstage-cli versions:bump [options] @@ -325,7 +402,14 @@ Options: ## versions:check -Check Backstage package versioning +Validate `@backstage` dependencies within the repo, making sure that there are +no duplicates of packages that might lead to breakages. For example, +`@backstage/core` must not be loaded in twice, so having two different versions +of it installed will cause this command to exit with an error. + +By supplying the `--fix` flag the command will attempt to fix any conflict that +can be resolved by editing `yarn.lock`, but will not attempt to search for +remote updates or modify any `package.json` files. ```text Usage: backstage-cli versions:check [options] @@ -337,7 +421,20 @@ Options: ## prepack -Prepares a package for packaging before publishing +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] @@ -348,7 +445,8 @@ Options: ## postpack -Restores the changes made by the prepack command +This should be added as `scripts.postpack` in all packages.return. It restores +`package.json` to what it looked like before calling the `prepack` command. ```text Usage: backstage-cli postpack [options] @@ -359,7 +457,7 @@ Options: ## clean -Delete cache directories +Remove cache and output directories. ```text Usage: backstage-cli clean [options] @@ -370,7 +468,9 @@ Options: ## build-workspace -Builds a temporary dist workspace from the provided packages +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`. ```text Usage: backstage-cli build-workspace [options]