diff --git a/docs/cli/commands.md b/docs/cli/commands.md index 4f3f43376c..dc226c6e2e 100644 --- a/docs/cli/commands.md +++ b/docs/cli/commands.md @@ -14,12 +14,13 @@ indicates where the command should be used by selecting from the following list: - `backend` - A backend package, such as `packages/backend`. - `frontend-plugin` - A frontend plugin package. - `backend-plugin` - A backend plugin package. -- `any` - Any kind of package. -- `root` - The monorepo root, not specific to any one package. +- `root` - The monorepo root. +- `any` - Any kind of package, but not the repo root. ## help -The following is a cleaned up output of of `yarn backstage-cli --help`: +This command displays you a help summary or detailed help screens for each +command. Below is a cleaned up output of `yarn backstage-cli --help`. ```text app:build Build an app for a production release @@ -59,13 +60,14 @@ help [command] display help for command Scope: `app` -Creates a bundle of static content from the app, which can then be served via -and static web server such as `nginx`, or via the `app-backend` plugin directly -from a Backstage backend instance. +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 with your own static content hosting -solution, this will be the final configuration used in the frontend, unless you +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` image in this repo along with its included run script, `APP_CONFIG_` environment variables will be injected into the frontend, and when serving using @@ -75,7 +77,7 @@ 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're can change that to +`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. @@ -93,16 +95,18 @@ process.env.BUILD_INFO = { ``` Some CI environments do not properly report correct resource limits, potentially -leading to errors such as `ENOMEM` during compilation. If you run into this you -can manually limit the parallelization of the build process by setting the -environment variable `BACKSTAGE_CLI_BUILD_PARALLEL` to for example `2`. +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`. You can set it to `false` +or `1` to completely disable parallelization, but usually a low value such as +`2` is enough. ```text Usage: backstage-cli app:build Options: --stats Write bundle stats to output directory - --config Config files to load instead of app-config.yaml (default: []) + --config <path> Config files to load instead of app-config.yaml (default: []) -h, --help display help for command ``` @@ -114,9 +118,7 @@ Diff an existing app with the template used in `@backstage/create-app`. This will verify that your app package has not diverged from the template, and can be useful to run after updating the version of `@backstage/cli` in your app. -This command is experimental and may be removed in the future. Compared to the -`plugin:diff` command this one is less valuable, as we have found fewer useful -checks to carry out. +This command is experimental and may be removed in the future. ```text Usage: backstage-cli app:diff @@ -132,13 +134,13 @@ Options: Scope: `app` Serve an app for local development. This starts up a local development server, -using a bundling config that is quite similar to the `app:build` command, but -with development features such as React Hot Module Replacement, faster -sourcemaps, no minification, etc. +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 as well, but there it -does not support watching, meaning that changes in for example `app-config.yaml` -are not reflected until the serve process is restarted. +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: @@ -147,18 +149,17 @@ process.env.NODE_ENV = 'development'; process.env.BUILD_INFO = { /* See app:build */ }; ``` -The serve configuration is controlled through the static configuration, by -default in `app-config.yaml`. The protocol of `app.baseUrl` determines whether -HTTP or HTTPS is used, and the listening host and port is also determined by the -URL. It is possible to override the listening host and port if needed by setting -`app.listen.host` and `app.listen.port`. +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`. ```text Usage: backstage-cli app:serve [options] Options: --check Enable type checking and linting - --config Config files to load instead of app-config.yaml (default: []) + --config <path> Config files to load instead of app-config.yaml (default: []) -h, --help display help for command ``` @@ -183,25 +184,24 @@ Options: Scope: `backend` -Builds a Docker image of the backend package and forwards all unknown options to +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 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 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 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. +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 @@ -212,9 +212,9 @@ 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. +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] @@ -237,7 +237,7 @@ Usage: backstage-cli backend:dev [options] Options: --check Enable type checking and linting --inspect Enable debugger - --config Config files to load instead of app-config.yaml (default: []) + --config <path> Config files to load instead of app-config.yaml (default: []) -h, --help display help for command ``` @@ -255,8 +255,8 @@ Usage: backstage-cli create-plugin [options] Options: --backend Create plugin with the backend dependencies as default - --scope npm scope - --npm-registry npm registry URL + --scope <scope> npm scope + --npm-registry <URL> npm registry URL --no-private Public npm package -h, --help display help for command ``` @@ -289,7 +289,7 @@ 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 +type declarations are expected to be found within `dist-types/` at the root of the monorepo. ```text @@ -316,7 +316,7 @@ Usage: backstage-cli plugin:serve [options] Options: --check Enable type checking and linting - --config Config files to load instead of app-config.yaml (default: []) + --config <path> Config files to load instead of app-config.yaml (default: []) -h, --help display help for command ``` @@ -356,7 +356,7 @@ first. Usage: backstage-cli build [options] Options: - --outputs List of formats to output [types,cjs,esm] + --outputs <formats> List of formats to output [types,cjs,esm] -h, --help display help for command ``` @@ -372,7 +372,7 @@ entire directory of no specific files are listed. Usage: backstage-cli lint [options] Options: - --format Lint report output format (default: "eslint-formatter-friendly") + --format <format> Lint report output format (default: "eslint-formatter-friendly") --fix Attempt to automatically fix violations -h, --help display help for command ``` @@ -397,15 +397,15 @@ configuration in the target package taking precedence. Refer to the configuration options. In addition to the Jest configuration there's an optional `transformModules` -option, which is an array of module names to transform. Normally modules inside -`node_modules` are not transformed, but there are cases were published packages -are not transpiled far enough to be supported by jest, in which case you need to -enable transforms of them. +option, which is an array of module names to include in transformations. +Normally modules inside `node_modules` are not transformed, but there are cases +were published packages are not transpiled far enough to be usable by Jest, in +which case you need to enable transform of them. Another way to override the Jest configuration is to place a `jest.config.js` or -`jest.config.ts` file in the package. As opposed to the `package.json` way of -overriding config, this completely removes the base config, and so you need to -set it up from scratch. +`jest.config.ts` file in the package root. As opposed to the `package.json` way +of overriding config, this completely removes the base config, and so you need +to set it up from scratch. ```text Usage: backstage-cli test [options] @@ -432,11 +432,11 @@ yarn backstage-cli config:print --frontend --package my-app Usage: backstage-cli config:print [options] Options: - --package Only load config schema that applies to the given package + --package <name> Only load config schema that applies to the given package --frontend Print only the frontend configuration --with-secrets Include secrets in the printed configuration - --format Format to print the configuration in, either json or yaml [yaml] - --config Config files to load instead of app-config.yaml (default: []) + --format <format> Format to print the configuration in, either json or yaml [yaml] + --config <path> Config files to load instead of app-config.yaml (default: []) -h, --help display help for command ``` @@ -452,8 +452,8 @@ local packages in the repo. Usage: backstage-cli config:check [options] Options: - --package Only load config schema that applies to the given package - --config Config files to load instead of app-config.yaml (default: []) + --package <name> Only load config schema that applies to the given package + --config <path> Config files to load instead of app-config.yaml (default: []) -h, --help display help for command ``` @@ -523,7 +523,7 @@ Options: Scope: `any` -This should be added as `scripts.postpack` in all packages.return. It restores +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 @@ -548,14 +548,14 @@ Options: ## build-workspace -Scope: `any` +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`. ```text -Usage: backstage-cli build-workspace [options] +Usage: backstage-cli build-workspace [options] <workspace-dir> Options: ``` diff --git a/docs/cli/index.md b/docs/cli/index.md index bfd9ac80da..064c1451b9 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -7,10 +7,12 @@ description: Overview of the Backstage CLI ## Summary Backstage provides an opinionated set of tooling for both frontend and backend -development. It is delivered through the `@backstage/cli` package and executed -either directly through `yarn backstage-cli ` or within yarn scripts. -When creating an app using `@backstage/create-app` it contains package scripts -for executing the most common commands. +development. It is delivered through the +[`@backstage/cli`](https://www.npmjs.com/package/@backstage/cli) package and +executed either directly through `yarn backstage-cli ` or within +`package.json` scripts. When creating an app using +[`@backstage/create-app`](https://www.npmjs.com/package/@backstage/create-app) +it contains package scripts for executing the most common commands. Under the hood the CLI uses [webpack](https://webpack.js.org/) for bundling, [rollup](https://rollupjs.org/) for building packages, @@ -18,69 +20,78 @@ Under the hood the CLI uses [webpack](https://webpack.js.org/) for bundling, linting. It also includes custom tooling for working within Backstage apps, for example for keeping the app up to date and verifying static configuration. +For a full list of CLI commands, see the [commands](./commands.md) page. + ## Introduction A goal of Backstage is to provide a delightful developer experience in and around the project. Creating new apps and plugins should be simple, iteration speed should be fast, and the overhead of maintaining custom tooling should be minimal. As a part of accomplishing this goal, Backstage provides its own set of -opinionated tooling, delivered primarily through the `@backstage/cli` package. +opinionated tooling, delivered primarily through the +[`@backstage/cli`](https://www.npmjs.com/package/@backstage/cli) package. -The `@backstage/cli` package provides a single `bin` script, `backstage-cli`, -which you can execute directly with `yarn` or within a script in `package.json`. -If you have a Backstage app set up, you can try out the following command to -print the top-level help page of the CLI: +The `@backstage/cli` package provides a single executable script, +`backstage-cli`, which you can run directly with `yarn` or within a script in +`package.json`. If you have a Backstage app set up, you can try out the +following command to print the top-level help page of the CLI: -```bash +```text yarn backstage-cli --help ``` -If you are familiar with `create-react-app` you may recognize this pattern, as -it uses a package called `react-scripts` to bring most of the functionality into -the created project. The Backstage equivalent of `create-react-app` is -`@backstage/create-app`, and the equivalent of `react-scripts` is -`@backstage/cli`. There are however a couple of key differences between the two. -Most notably, Backstage apps are monorepos and the CLI is tailored for that -environment. It provides tooling both for bundling and developing full end-user -apps, but also for developing, building and publishing individual packages -within the monorepo. +If you are familiar with [`create-react-app`](https://create-react-app.dev/) you +may recognize the pattern of bundling tooling up as a CLI, as it uses a package +called [`react-scripts`](https://www.npmjs.com/package/react-scripts) to bring +most of the functionality into the created project. The Backstage equivalent of +`create-react-app` is +[`@backstage/create-app`](https://www.npmjs.com/package/@backstage/create-app), +and the equivalent of `react-scripts` is `@backstage/cli`. There are however a +couple of key differences between the two. Most notably, Backstage apps are +monorepos and the CLI is tailored for that environment. It provides tooling both +for bundling and developing full end-user apps, but also for developing, +building and publishing individual packages within the monorepo, as well as +tooling that is more unique to Backstage, such as commands for working with +static configuration. -## Opinionated +## Opinionated Tooling -The Backstage CLI is highly opinionated in what tools to use and how they are +The Backstage CLI is highly opinionated in what tools are used and how they are configured. It is tailored for development in large TypeScript monorepos with -hundreds of separate plugins, but with the ability to have edits anywhere in the -codebase reflected within a few seconds. The build output is also optimized for -this setup, and aims for an excellent user experience with fast page load times -in modern browsers, rather than a wide range of support. +hundreds of separate packages, but with the ability to have edits anywhere in +the codebase reflected within a few seconds. The build output is also optimized +for this setup, and aims to provide an excellent user experience with fast page +load times in modern browsers, rather than a wide range of support. While the Backstage tooling is opinionated in how to develop and build packages, it is also possible to use your own tooling either partially or fully. For example, the CLI provides a command for building a plugin package for -publishing, but the output is a pretty regular `types+js` output that you see in -many packages, which can easily be achieved with many other sets of tooling. +publishing, but the output is a quite standard combination of transpiled +JavaScript and TypeScript type declarations. The usage of the command from the +CLI can therefore easily be replaced with other tools if necessary. Just like `react-scripts`, the Backstage CLI does not provide many hooks for overriding or customizing the build process. This is to allow for evolution of the CLI without having to take a wide API surface into account. Allowing us to -more quickly iterate and improve the tooling, as well more easily keeping -dependencies up to date. +quickly iterate and improve the tooling, as well more easily keep dependencies +up to date. -## Opinions +## Opinions & Goals In no particular order, this is a list of opinions and goals that guide the design and development of the Backstage CLI: - All you need for development is `yarn start`, there should be no need to - manually build packages or run other tasks on the side. + manually build packages or run other separate tasks. - Development experience comes first. The toolchain is optimized for keeping development smooth, rather than making it easy to for example build and publish packages. -- TypeChecking and linting is left for editors and CI. Most code editors provide - tooling for these checks, and running them again during compilation would slow - down iteration speed and consume more resources. +- Type checking and linting is left for text editors and Continuous Integration. + Most text editors provide tooling for these checks, and running them a second + time during compilation slows down iteration speed and consumes more system + resources. - Backstage is run in modern browsers. We keep transpilation lightweight and - rely on modern technology such as HTTP/2 to optimize frontend speed. + rely on modern technologies such as HTTP/2 to optimize frontend speed. ## Glossary