From c7507fe2404952e4c6e15e115fdd3955125316ea Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 13 Dec 2020 13:15:01 +0100 Subject: [PATCH 01/12] docs: initial cli docs skeleton + commands extraction --- docs/cli/commands.md | 312 +++++++++++++++++++++++++++++++++++++ docs/cli/index.md | 31 ++++ docs/cli/under-the-hood.md | 7 + microsite/sidebars.json | 5 + 4 files changed, 355 insertions(+) create mode 100644 docs/cli/commands.md create mode 100644 docs/cli/index.md create mode 100644 docs/cli/under-the-hood.md diff --git a/docs/cli/commands.md b/docs/cli/commands.md new file mode 100644 index 0000000000..f10186a829 --- /dev/null +++ b/docs/cli/commands.md @@ -0,0 +1,312 @@ +--- +id: commands +title: Commands +description: Descriptions of all commands available in the CLI. +--- + +## Summary + +```text +app:build [options] Build an app for a production release +app:diff [options] Diff an existing app with the creation template +app:serve [options] Serve an app for local development + +backend:build Build a backend plugin +backend:build-image [options] Bundles the package into a docker image. All extra args are forwarded to `docker image build`. +backend:dev [options] Start local development server with HMR for the backend + +plugin:build Build a plugin +plugin:diff [options] Diff an existing plugin with the creation template +plugin:serve [options] Serves the dev/ folder of a plugin + +build [options] Build a package for publishing +build-workspace Builds a temporary dist workspace from the provided packages +lint [options] Lint a package +test Run tests, forwarding args to Jest, defaulting to watch mode +clean Delete cache directories + +create-plugin [options] Creates a new plugin in the current repository +remove-plugin Removes plugin in the current repository + +config:print [options] Print the app configuration for the current package +config:check [options] Validate that the given configuration loads and matches schema + +versions:bump Bump Backstage packages to the latest versions +versions:check [options] Check Backstage package versioning + +prepack Prepares a package for packaging before publishing +postpack Restores the changes made by the prepack command + +help [command] display help for command +``` + +## app:build + +Build an app for a production release + +```text +Usage: backstage-cli app:build [options] + +Options: + --stats Write bundle stats to output directory + --config Config files to load instead of app-config.yaml (default: []) + -h, --help display help for command +``` + +## app:diff + +Diff an existing app with the creation template + +```text +Usage: backstage-cli app:diff [options] + +Options: + --check Fail if changes are required + --yes Apply all changes + -h, --help display help for command +``` + +## app:serve + +Serve an app for local development + +```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: []) + -h, --help display help for command +``` + +## backend:build + +Build a backend plugin + +```text +Usage: backstage-cli backend:build [options] + +Options: + -h, --help display help for command +``` + +## backend:build-image + +Bundles the package into a docker image. All extra args are forwarded to +`docker image build`. + +```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 + +Start local development server with HMR for the backend + +```text +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: []) + -h, --help display help for command +``` + +## create-plugin + +Creates a new plugin in the current repository + +```text +Usage: backstage-cli create-plugin [options] + +Options: + --backend Create plugin with the backend dependencies as default + --scope npm scope + --npm-registry npm registry URL + --no-private Public npm package + -h, --help display help for command +``` + +## remove-plugin + +Removes plugin in the current repository + +```text +Usage: backstage-cli remove-plugin [options] + +Options: + -h, --help display help for command +``` + +## plugin:build + +Build a plugin + +```text +Usage: backstage-cli plugin:build [options] + +Options: + -h, --help display help for command +``` + +## plugin:serve + +Serves the dev/ folder of a plugin + +```text +Usage: backstage-cli plugin:serve [options] + +Options: + --check Enable type checking and linting + --config Config files to load instead of app-config.yaml (default: []) + -h, --help display help for command +``` + +## plugin:diff + +Diff an existing plugin with the creation template + +```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 + +Build a package for publishing + +```text +Usage: backstage-cli build [options] + +Options: + --outputs List of formats to output [types,cjs,esm] + -h, --help display help for command +``` + +## lint + +Lint a package + +```text +Usage: backstage-cli lint [options] + +Options: + --format Lint report output format (default: "eslint-formatter-friendly") + --fix Attempt to automatically fix violations + -h, --help display help for command +``` + +## test + +Run tests, forwarding args to Jest, defaulting to watch mode + +```text +Usage: backstage-cli test [options] + +Options: + --backstage-cli-help display help for command +``` + +## config:print + +Print the app configuration for the current package + +```text +Usage: backstage-cli config:print [options] + +Options: + --package 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: []) + -h, --help display help for command +``` + +## config:check + +Validate that the given configuration loads and matches schema + +```text +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: []) + -h, --help display help for command +``` + +## versions:bump + +Bump Backstage packages to the latest versions + +```text +Usage: backstage-cli versions:bump [options] + +Options: + -h, --help display help for command +``` + +## versions:check + +Check Backstage package versioning + +```text +Usage: backstage-cli versions:check [options] + +Options: + --fix Fix any auto-fixable versioning problems + -h, --help display help for command +``` + +## prepack + +Prepares a package for packaging before publishing + +```text +Usage: backstage-cli prepack [options] + +Options: + -h, --help display help for command +``` + +## postpack + +Restores the changes made by the prepack command + +```text +Usage: backstage-cli postpack [options] + +Options: + -h, --help display help for command +``` + +## clean + +Delete cache directories + +```text +Usage: backstage-cli clean [options] + +Options: + -h, --help display help for command +``` + +## build-workspace + +Builds a temporary dist workspace from the provided packages + +```text +Usage: backstage-cli build-workspace [options] + +Options: +``` diff --git a/docs/cli/index.md b/docs/cli/index.md new file mode 100644 index 0000000000..9532e05993 --- /dev/null +++ b/docs/cli/index.md @@ -0,0 +1,31 @@ +--- +id: index +title: Overview +description: Overview of the Backstage CLI +--- + +## Summary + +Backstage ships its own CLI tooling + +Tooling both for bundling deployment artifacts, as well as building individual +packages for publishing. + +Under the hook we use [webpack](https://webpack.js.org/) for bundling, +[rollup](https://rollupjs.org/) for building packages, +[jest](https://jestjs.io/) for testing, and [eslint](https://eslint.org/) for +linting. + +## Glossary + +- **Package** - A package in the Node.js ecosystem, often published to a package + registry such as [NPM](https://www.npmjs.com/). +- **Monorepo** - A project layout that consists of multiple packages within a + single project, where packages are able to have local dependencies on each + other. Often enabled through tooling such as [lerna](https://lerna.js.org/) + and [yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/) +- **Local Package** - One of the packages within a monorepo. These package may + or may not also be published to a package registry. +- **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. diff --git a/docs/cli/under-the-hood.md b/docs/cli/under-the-hood.md new file mode 100644 index 0000000000..f7400b2037 --- /dev/null +++ b/docs/cli/under-the-hood.md @@ -0,0 +1,7 @@ +--- +id: under-the-hood +title: Under the Hook +description: A dive into the implementation of the Backstage CLI +--- + +## Summary diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 91112dd3b3..8d2c382b9a 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -34,6 +34,11 @@ ] } ], + "CLI": [ + "cli/index", + "cli/commands", + "cli/under-the-hood" + ], "Core Features": [ { "type": "subcategory", From 4e45c5953138cb4bcca7fcdde4cab333702e1de8 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 13 Dec 2020 14:15:56 +0100 Subject: [PATCH 02/12] docs/cli: flesh out index page --- docs/cli/index.md | 62 ++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 56 insertions(+), 6 deletions(-) diff --git a/docs/cli/index.md b/docs/cli/index.md index 9532e05993..eb0678aad8 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -6,15 +6,65 @@ description: Overview of the Backstage CLI ## Summary -Backstage ships its own CLI tooling +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. -Tooling both for bundling deployment artifacts, as well as building individual -packages for publishing. - -Under the hook we use [webpack](https://webpack.js.org/) for bundling, +Under the hood the CLI uses [webpack](https://webpack.js.org/) for bundling, [rollup](https://rollupjs.org/) for building packages, [jest](https://jestjs.io/) for testing, and [eslint](https://eslint.org/) for -linting. +linting. It also includes custom tooling for working within Backstage apps, for +example for keeping the app up to date and verifying static configuration. + +## 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. + +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: + +```bash +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. + +## Opinionated + +The Backstage CLI is highly opinionated in what tools to use 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. + +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. + +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. ## Glossary From e548156182a973ed4b459e18533afc22c85ffff8 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 13 Dec 2020 15:03:01 +0100 Subject: [PATCH 03/12] docs/cli: add some opinions --- docs/cli/index.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/cli/index.md b/docs/cli/index.md index eb0678aad8..bfd9ac80da 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -66,6 +66,22 @@ 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. +## Opinions + +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. +- 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. +- Backstage is run in modern browsers. We keep transpilation lightweight and + rely on modern technology such as HTTP/2 to optimize frontend speed. + ## Glossary - **Package** - A package in the Node.js ecosystem, often published to a package From aec651f8204c476026a260f63bd0c878a79c6284 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 13 Dec 2020 15:45:01 +0100 Subject: [PATCH 04/12] docs/cli: add detailed descriptions for a couple of commands --- docs/cli/commands.md | 75 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 71 insertions(+), 4 deletions(-) diff --git a/docs/cli/commands.md b/docs/cli/commands.md index f10186a829..ef35f0ad8f 100644 --- a/docs/cli/commands.md +++ b/docs/cli/commands.md @@ -42,7 +42,43 @@ help [command] display help for command ## app:build -Build an app for a production release +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. + +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 +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 +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're 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 you +can manually limit the parallelization of the build process by setting the +environment variable `BACKSTAGE_CLI_BUILD_PARALLEL` to for example `2`. ```text Usage: backstage-cli app:build [options] @@ -55,7 +91,13 @@ Options: ## app:diff -Diff an existing app with the creation template +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. ```text Usage: backstage-cli app:diff [options] @@ -68,7 +110,29 @@ Options: ## app:serve -Serve an app for local development +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. + +The serve configuration is controlled through the static configuration, by +default in `app-config.yaml`. The schema in the `app.baseUrl` determines whether +HTTP or HTTPS is used, and the listening host and port port is also determined +from the URL. It is possible to explicitly override the listening host and port +if needed by setting `app.listen.host` and `app.listen.port`. + +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. + +During the build, the following variables are set: + +```java +process.env.NODE_ENV = 'development'; +process.env.BUILD_INFO = { /* See app:build */ }; +``` + +By default the ```text Usage: backstage-cli app:serve [options] @@ -81,7 +145,10 @@ Options: ## backend:build -Build a backend plugin +This builds a backend package for publish 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. ```text Usage: backstage-cli backend:build [options] From 2b29cb9eecdb3b5a97a62a0daf006eb1a2cb8f69 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 13 Dec 2020 17:30:02 +0100 Subject: [PATCH 05/12] docs/cli: detailed descriptions for all commands --- docs/cli/commands.md | 138 +++++++++++++++++++++++++++++++++++++------ 1 file changed, 119 insertions(+), 19 deletions(-) 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] From 6b3b1fb55fe07cec30673076d23c45f93b5eae6a Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 13 Dec 2020 17:44:24 +0100 Subject: [PATCH 06/12] docs/cli: tweak commands doc and add scope of each command --- docs/cli/commands.md | 128 +++++++++++++++++++++++++++++++------------ 1 file changed, 93 insertions(+), 35 deletions(-) diff --git a/docs/cli/commands.md b/docs/cli/commands.md index 8f8cb74ed7..5fc9608ff0 100644 --- a/docs/cli/commands.md +++ b/docs/cli/commands.md @@ -4,44 +4,61 @@ title: Commands description: Descriptions of all commands available in the CLI. --- -## Summary +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. +- `any` - Any kind of package. +- `root` - The monorepo root, not specific to any one package. + +## help + +The following is a cleaned up output of of `yarn backstage-cli --help`: ```text -app:build [options] Build an app for a production release -app:diff [options] Diff an existing app with the creation template -app:serve [options] Serve an app for local development +app:build Build an app for a production release +app:diff Diff an existing app with the creation template +app:serve Serve an app for local development -backend:build Build a backend plugin -backend:build-image [options] Bundles the package into a docker image. All extra args are forwarded to `docker image build`. -backend:dev [options] Start local development server with HMR for the backend +backend:build Build a backend plugin +backend:build-image Bundles the package into a docker image +backend:dev Start local development server with HMR for the backend -plugin:build Build a plugin -plugin:diff [options] Diff an existing plugin with the creation template -plugin:serve [options] Serves the dev/ folder of a plugin +plugin:build Build a plugin +plugin:diff Diff an existing plugin with the creation template +plugin:serve Serves the dev/ folder of a plugin -build [options] Build a package for publishing -build-workspace Builds a temporary dist workspace from the provided packages -lint [options] Lint a package -test Run tests, forwarding args to Jest, defaulting to watch mode -clean Delete cache directories +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 -create-plugin [options] Creates a new plugin in the current repository -remove-plugin Removes plugin in the current repository +create-plugin Creates a new plugin in the current repository +remove-plugin Removes plugin in the current repository -config:print [options] Print the app configuration for the current package -config:check [options] Validate that the given configuration loads and matches schema +config:print Print the app configuration for the current package +config:check Validate that the given configuration loads and matches schema -versions:bump Bump Backstage packages to the latest versions -versions:check [options] Check Backstage package versioning +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 +prepack Prepares a package for packaging before publishing +postpack Restores the changes made by the prepack command -help [command] display help for command +help [command] display help for command ``` ## app:build +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. @@ -81,7 +98,7 @@ can manually limit the parallelization of the build process by setting the environment variable `BACKSTAGE_CLI_BUILD_PARALLEL` to for example `2`. ```text -Usage: backstage-cli app:build [options] +Usage: backstage-cli app:build Options: --stats Write bundle stats to output directory @@ -91,6 +108,8 @@ Options: ## app:diff +Scope: `app` + 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. @@ -100,7 +119,7 @@ This command is experimental and may be removed in the future. Compared to the checks to carry out. ```text -Usage: backstage-cli app:diff [options] +Usage: backstage-cli app:diff Options: --check Fail if changes are required @@ -110,17 +129,13 @@ Options: ## app:serve +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. -The serve configuration is controlled through the static configuration, by -default in `app-config.yaml`. The schema in the `app.baseUrl` determines whether -HTTP or HTTPS is used, and the listening host and port port is also determined -from the URL. It is possible to explicitly override the listening host and port -if needed by setting `app.listen.host` and `app.listen.port`. - 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. @@ -132,7 +147,11 @@ process.env.NODE_ENV = 'development'; process.env.BUILD_INFO = { /* See app:build */ }; ``` -By default the +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`. ```text Usage: backstage-cli app:serve [options] @@ -145,10 +164,13 @@ Options: ## backend:build -This builds a backend package for publish and use in production. The build +Scope: `backend`, `backend-plugin` (To be replaced by `backend:bundle` for +`backend`) + +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. +common example being the `migrations` directory. ```text Usage: backstage-cli backend:build [options] @@ -159,6 +181,8 @@ Options: ## backend:build-image +Scope: `backend` + Builds a Docker image of the backend package and forwards all unknown options to `docker image build`. For example: @@ -202,6 +226,8 @@ Options: ## backend:dev +Scope: `backend`, `backend-plugin` + Starts a backend package in development mode, with watch mode enabled for all local packages. @@ -217,6 +243,8 @@ Options: ## 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 @@ -235,6 +263,8 @@ Options: ## remove-plugin +Scope: `root` + A utility to remove a plugin from a repo, essentially undoing everything that was done by `create-plugin`. @@ -250,6 +280,8 @@ Options: ## 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 @@ -269,6 +301,8 @@ Options: ## 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. @@ -288,6 +322,8 @@ Options: ## 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 @@ -304,6 +340,8 @@ Options: ## 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 @@ -324,6 +362,8 @@ Options: ## 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 of no specific files are listed. @@ -339,6 +379,8 @@ Options: ## test +Scope: `any` + Run tests, forwarding all unknown options to Jest, and defaulting to watch mode. ```text @@ -350,6 +392,8 @@ Options: ## 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. @@ -374,6 +418,8 @@ 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. @@ -389,6 +435,8 @@ Options: ## versions:bump +Scope: `root` + 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. @@ -402,6 +450,8 @@ 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. For example, `@backstage/core` must not be loaded in twice, so having two different versions @@ -421,6 +471,8 @@ Options: ## 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`. @@ -445,6 +497,8 @@ Options: ## postpack +Scope: `any` + 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. @@ -457,6 +511,8 @@ Options: ## clean +Scope: `any` + Remove cache and output directories. ```text @@ -468,6 +524,8 @@ Options: ## build-workspace +Scope: `any` + 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`. From 842f745fbd8b249ac3fa84cea629f0de4a24d450 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 13 Dec 2020 18:58:48 +0100 Subject: [PATCH 07/12] docs/cli: more docs for the test command --- docs/cli/commands.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/cli/commands.md b/docs/cli/commands.md index 5fc9608ff0..4f3f43376c 100644 --- a/docs/cli/commands.md +++ b/docs/cli/commands.md @@ -382,6 +382,30 @@ Options: 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. + +If needed, the configuration can be extended using a `"jest"` field in +`package.json`, both within the target package and the monorepo root, with +configuration in the target package taking precedence. Refer to the +[Jest configuration](https://jestjs.io/docs/en/configuration) for a full list of +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. + +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. ```text Usage: backstage-cli test [options] From e0426d00edb528bf82e74b3a65c960b8f3c0ffa0 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 13 Dec 2020 19:00:44 +0100 Subject: [PATCH 08/12] docs/cli: skip under the hood docs for now --- docs/cli/under-the-hood.md | 7 ------- microsite/sidebars.json | 6 +----- 2 files changed, 1 insertion(+), 12 deletions(-) delete mode 100644 docs/cli/under-the-hood.md diff --git a/docs/cli/under-the-hood.md b/docs/cli/under-the-hood.md deleted file mode 100644 index f7400b2037..0000000000 --- a/docs/cli/under-the-hood.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -id: under-the-hood -title: Under the Hook -description: A dive into the implementation of the Backstage CLI ---- - -## Summary diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 8d2c382b9a..b31f0ccdf3 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -34,11 +34,7 @@ ] } ], - "CLI": [ - "cli/index", - "cli/commands", - "cli/under-the-hood" - ], + "CLI": ["cli/index", "cli/commands"], "Core Features": [ { "type": "subcategory", From 436202b20efb763130e14430a422ca1ffe975704 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 13 Dec 2020 19:48:22 +0100 Subject: [PATCH 09/12] docs/cli: text fixes --- docs/cli/commands.md | 124 +++++++++++++++++++++---------------------- docs/cli/index.md | 81 ++++++++++++++++------------ 2 files changed, 108 insertions(+), 97 deletions(-) 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 From a9d6779f38b7f5ff6d5f80359d3454aac695ad0d Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 13 Dec 2020 19:52:09 +0100 Subject: [PATCH 10/12] docs/cli: vocab updates --- .github/styles/vocab.txt | 6 ++++++ docs/cli/index.md | 6 +++--- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/.github/styles/vocab.txt b/.github/styles/vocab.txt index 5008e88dae..d00ef23437 100644 --- a/.github/styles/vocab.txt +++ b/.github/styles/vocab.txt @@ -139,14 +139,17 @@ Oldsberg onboarding Onboarding pagerduty +parallelization Patrik Phoen plantuml Pomaceous postgres +postpack pre prebaked preconfigured +prepack Preprarer Prerequisities productional @@ -184,6 +187,7 @@ Serverless Sinon smartsymobls Snyk +sourcemaps sparklines Spotifiers spotify @@ -217,6 +221,8 @@ toolsets tooltip tooltips touchpoints +transpiled +transpilation ui untracked upvote diff --git a/docs/cli/index.md b/docs/cli/index.md index 064c1451b9..4a60a1bf1b 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -14,9 +14,9 @@ executed either directly through `yarn backstage-cli ` or within [`@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, -[jest](https://jestjs.io/) for testing, and [eslint](https://eslint.org/) for +Under the hood the CLI uses [Webpack](https://webpack.js.org/) for bundling, +[Rollup](https://rollupjs.org/) for building packages, +[Jest](https://jestjs.io/) for testing, and [eslint](https://eslint.org/) for linting. It also includes custom tooling for working within Backstage apps, for example for keeping the app up to date and verifying static configuration. From 05651c14315aba13951c8d728d4a5a855a08cb89 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 15 Dec 2020 10:00:43 +0100 Subject: [PATCH 11/12] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fredrik Adelöw --- docs/cli/commands.md | 12 ++++++------ docs/cli/index.md | 4 ++-- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/cli/commands.md b/docs/cli/commands.md index dc226c6e2e..6e814406ef 100644 --- a/docs/cli/commands.md +++ b/docs/cli/commands.md @@ -19,7 +19,7 @@ indicates where the command should be used by selecting from the following list: ## help -This command displays you a help summary or detailed help screens for each +This command displays a help summary or detailed help screens for each command. Below is a cleaned up output of `yarn backstage-cli --help`. ```text @@ -69,7 +69,7 @@ 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` image in this repo along with its included run script, `APP_CONFIG_` +`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 @@ -229,7 +229,7 @@ Options: Scope: `backend`, `backend-plugin` Starts a backend package in development mode, with watch mode enabled for all -local packages. +local dependencies. ```text Usage: backstage-cli backend:dev [options] @@ -366,7 +366,7 @@ 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 of no specific files are listed. +entire directory if no specific files are listed. ```text Usage: backstage-cli lint [options] @@ -393,7 +393,7 @@ location. If needed, the configuration can be extended using a `"jest"` field in `package.json`, both within the target package and the monorepo root, with configuration in the target package taking precedence. Refer to the -[Jest configuration](https://jestjs.io/docs/en/configuration) for a full list of +[Jest configuration documentation](https://jestjs.io/docs/en/configuration) for a full list of configuration options. In addition to the Jest configuration there's an optional `transformModules` @@ -461,7 +461,7 @@ Options: Scope: `root` -Bump all `@backstage` packages to the latest versions. This check for updates in +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. diff --git a/docs/cli/index.md b/docs/cli/index.md index 4a60a1bf1b..9e5954f839 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -72,8 +72,8 @@ 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 -quickly iterate and improve the tooling, as well more easily keep dependencies +the CLI without having to take a wide API surface into account. This allows us to +quickly iterate and improve the tooling, as well as to more easily keep dependencies up to date. ## Opinions & Goals From 15dce70a5d508cee660f5a6e2642e8c0573892c0 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 15 Dec 2020 10:16:57 +0100 Subject: [PATCH 12/12] docs/cli: review updates --- docs/cli/commands.md | 34 ++++++++++++++++------------------ docs/cli/index.md | 6 +++--- 2 files changed, 19 insertions(+), 21 deletions(-) diff --git a/docs/cli/commands.md b/docs/cli/commands.md index 6e814406ef..c505bf8ae7 100644 --- a/docs/cli/commands.md +++ b/docs/cli/commands.md @@ -19,8 +19,8 @@ indicates where the command should be used by selecting from the following list: ## 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`. +This command displays 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 @@ -69,11 +69,11 @@ 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. +`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 @@ -97,9 +97,10 @@ 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 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. +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. ```text Usage: backstage-cli app:build @@ -165,8 +166,7 @@ Options: ## backend:build -Scope: `backend`, `backend-plugin` (To be replaced by `backend:bundle` for -`backend`) +Scope: `backend`, `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 @@ -393,8 +393,8 @@ location. If needed, the configuration can be extended using a `"jest"` field in `package.json`, both within the target package and the monorepo root, with configuration in the target package taking precedence. Refer to the -[Jest configuration documentation](https://jestjs.io/docs/en/configuration) for a full list of -configuration options. +[Jest configuration documentation](https://jestjs.io/docs/en/configuration) for +a full list of configuration options. In addition to the Jest configuration there's an optional `transformModules` option, which is an array of module names to include in transformations. @@ -461,8 +461,8 @@ Options: 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 +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. ```text @@ -556,6 +556,4 @@ the resulting archive in the target `workspace-dir`. ```text Usage: backstage-cli build-workspace [options] <workspace-dir> - -Options: ``` diff --git a/docs/cli/index.md b/docs/cli/index.md index 9e5954f839..1b2e01be62 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -72,9 +72,9 @@ 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. This allows us to -quickly iterate and improve the tooling, as well as to more easily keep dependencies -up to date. +the CLI without having to take a wide API surface into account. This allows us +to quickly iterate and improve the tooling, as well as to more easily keep +dependencies up to date. ## Opinions & Goals