diff --git a/docs/local-dev/cli-build-system.md b/docs/local-dev/cli-build-system.md index 91767d3b60..a850673090 100644 --- a/docs/local-dev/cli-build-system.md +++ b/docs/local-dev/cli-build-system.md @@ -326,13 +326,25 @@ correctly from linked in packages, the `ModuleScopePlugin` from [`react-dev-utils`](https://www.npmjs.com/package/react-dev-utils) which makes sure that imports don't reach outside the package, a few fallbacks for some Node.js modules like `'buffer'` and `'events'`, a plugin that writes the -frontend configuration to the bundle as `process.env.APP_CONFIG` and build -information as `process.env.BUILD_INFO`, and lastly minification handled by +frontend configuration to the bundle as `process.env.APP_CONFIG`, and lastly minification handled by [esbuild](https://esbuild.github.io/) using the [`esbuild-loader`](https://npm.im/esbuild-loader). There are of course also a set of loaders configured, which you can read more about in the [loaders](#loaders) and [transpilation](#transpilation) sections. +During the build, the following constants are also set: + +```java +process.env.NODE_ENV = 'production'; +process.env.BUILD_INFO = { + cliVersion: '0.4.0', // The version of the CLI package + gitVersion: 'v0.4.0-86-ge54815618', // output of `git describe --always` + packageVersion: '1.0.5', // The version of the app package itself + timestamp: 1678900000000, // Date.now() when the build started + commit: 'e548156182a973ed4b459e18533afc22c85ffff8', // output of `git rev-parse HEAD` +}; +``` + The output of the bundling process is split into two categories of files with separate caching strategies. The first is a set of generic assets with plain names in the root of the `dist/` folder. You will want to serve these with diff --git a/docs/local-dev/cli-commands.md b/docs/local-dev/cli-commands.md index eff6404e3b..78c311e5cf 100644 --- a/docs/local-dev/cli-commands.md +++ b/docs/local-dev/cli-commands.md @@ -7,251 +7,202 @@ description: Descriptions of all commands available in the CLI. This page lists all commands provided by the Backstage CLI, what they're for, and where to use them. -The documentation for each command begins with specifying its scope, this -indicates where the command should be used by selecting from the following list: - -- `app` - A frontend app package, such as `packages/app`. -- `backend` - A backend package, such as `packages/backend`. -- `frontend-plugin` - A frontend plugin package. -- `backend-plugin` - A backend plugin package. -- `root` - The monorepo root. -- `any` - Any kind of package, but not the repo root. - ## help This command displays a help summary or detailed help screens for each command. -Below is a cleaned up output of `yarn backstage-cli --help`. +Below is a cleaned up output of `yarn backstage-cli --help` ```text -app:build Build an app for a production release -app:serve Serve an app for local development +repo [command] Command that run across an entire Backstage project +package [command] Lifecycle scripts for individual packages +migrate [command] Migration utilities -backend:build Build a backend plugin -backend:bundle Bundle the backend into a deployment archive -backend:build-image Bundles the package into a docker image -backend:dev Start local development server with HMR for the backend +create Open up an interactive guide to creating new things in your app -plugin:build Build a plugin -plugin:diff Diff an existing plugin with the creation template -plugin:serve Serves the dev/ folder of a plugin +config:docs Browse the configuration reference documentation +config:print Print the app configuration for the current package +config:check Validate that the given configuration loads and matches schema +config:schema Dump the app configuration schema -build Build a package for publishing -build-workspace Builds a temporary dist workspace from the provided packages -lint Lint a package -test Run tests, forwarding args to Jest, defaulting to watch mode -clean Delete cache directories +versions:bump Bump Backstage packages to the latest versions +versions:check Check Backstage package versioning -create Open up an interactive guide to creating new things in your app -create-plugin Creates a new plugin in the current repository -remove-plugin Removes plugin in the current repository +build-workspace Builds a temporary dist workspace from the provided packages +create-github-app Create new GitHub App in your organization (experimental) -config:docs Browse the configuration reference documentation -config:print Print the app configuration for the current package -config:check Validate that the given configuration loads and matches schema -config:schema Dump the app configuration schema - -versions:bump Bump Backstage packages to the latest versions -versions:check Check Backstage package versioning - -prepack Prepares a package for packaging before publishing -postpack Restores the changes made by the prepack command - -create-github-app Create new GitHub App in your organization (experimental) - -info Show helpful information for debugging and reporting bugs -help [command] display help for command +info Show helpful information for debugging and reporting bugs +help [command] display help for command ``` -## app:build - -Scope: `app` - -Builds a bundle of static content from the app, which can then be served via any -static web server such as `nginx`, or via the -[`app-backend`](https://www.npmjs.com/package/@backstage/plugin-app-backend) -plugin directly from a Backstage backend instance. - -The command also reads and injects static configuration into the bundle. It is -important to note that when deploying using your own static content hosting -solution, this will be the final configuration used in the frontend unless you -for example hook in configuration loading from the backend. When using the -`nginx` based Dockerfile in this repo along with its included run script, -`APP_CONFIG_` environment variables will be injected into the frontend, and when -serving using the `app-backend` plugin, the configuration is completely injected -from the backend and the configuration at the time of calling this command will -not be used. - -Note that even when injecting configuration at runtime, it is not possible to -change the base path of the app. For example, if you at build time have -`app.baseUrl` set to `http://dev-app.com/my-app`, you can change that to -`https://prod-app.com/my-app`, but not to `https://prod-app.com`, as that would -change the path. - -During the build, the following variables are set: - -```java -process.env.NODE_ENV = 'production'; -process.env.BUILD_INFO = { - cliVersion: '0.4.0', // The version of the CLI package - gitVersion: 'v0.4.0-86-ge54815618', // output of `git describe --always` - packageVersion: '1.0.5', // The version of the app package itself - timestamp: 1678900000000, // Date.now() when the build started - commit: 'e548156182a973ed4b459e18533afc22c85ffff8', // output of `git rev-parse HEAD` -}; -``` - -Some CI environments do not properly report correct resource limits, potentially -leading to errors such as `ENOMEM` during compilation. If you run into this -issue you can limit the parallelization of the build process by setting the -environment variable `BACKSTAGE_CLI_BUILD_PARALLEL`, which is forwarded to the -[`terser-webpack-plugin`](https://github.com/webpack-contrib/terser-webpack-plugin#parallel). -You can set it to `false` or `1` to completely disable parallelization, but -usually a low value such as `2` is enough. +The `package` command category, `yarn backstage-cli package --help` ```text -Usage: backstage-cli app:build +start [options] Start a package for local development +build [options] Build a package for production deployment or publishing +lint [options] Lint a package +test Run tests, forwarding args to Jest, defaulting to watch mode +clean Delete cache directories +prepack Prepares a package for packaging before publishing +postpack Restores the changes made by the prepack command +``` + +The `repo` command category, `yarn backstage-cli repo --help` + +```text +build [options] Build packages in the project, excluding bundled app and backend packages. +lint [options] Lint all packages in the project +``` + +The `migrate` command category, `yarn backstage-cli migrate --help` + +```text +package-roles Add package role field to packages that don't have it +package-scripts Set package scripts according to each package role +package-lint-configs Migrates all packages to use @backstage/cli/config/eslint-factory +``` + +## repo build + +Builds all packages in the project, excluding bundled packages by default, i.e. ones +with the role `'frontend'` or `'backend'`. + +```text +Usage: backstage-cli repo build [options] + +Build packages in the project, excluding bundled app and backend packages. + +Options: + --all Build all packages, including bundled app and backend packages. + --since <ref> Only build packages and their dev dependents that changed since the specified ref +``` + +## repo lint + +Lint all packages in the project. + +```text +Usage: backstage-cli repo lint [options] + +Lint all packages in the project + +Options: + --format <format> Lint report output format (default: "eslint-formatter-friendly") + --since <ref> Only lint packages that changed since the specified ref + --fix Attempt to automatically fix violations +``` + +## package start + +Starts the package for local development. See the frontend and backend development parts in the build system [bundling](./cli-build-system#bundling) section for more details. + +```text +Usage: backstage-cli package start [options] + +Start a package for local development Options: - --stats Write bundle stats to output directory - --lax Do not require environment variables to be set --config <path> Config files to load instead of app-config.yaml (default: []) - -h, --help display help for command + --role <name> Run the command with an explicit package role + --check Enable type checking and linting if available + --inspect Enable debugger in Node.js environments + --inspect-brk Enable debugger in Node.js environments, breaking before code starts ``` -## app:serve +## package build -Scope: `app` - -Serve an app for local development. This starts up a local development server, -using a bundling configuration that is quite similar to that of the `app:build` -command, but with development features such as React Hot Module Replacement, -faster sourcemaps, no minification, etc. - -The static configuration is injected into the frontend, but it does not support -watching, meaning that changes in for example `app-config.yaml` are not -reflected until the serve process is restarted. - -During the build, the following variables are set: - -```java -process.env.NODE_ENV = 'development'; -process.env.BUILD_INFO = { /* See app:build */ }; -``` - -The server listening configuration is controlled through the static -configuration. The `app.baseUrl` determines the listening host and port, as well -as whether HTTPS is used or not. It is also possible to override the listening -host and port if needed by setting `app.listen.host` and `app.listen.port`. +Build an individual package based on its role. See the build system [building](./cli-build-system#building) and [bundling](./cli-build-system#bundling) sections for more details. ```text -Usage: backstage-cli app:serve [options] +Usage: backstage-cli package build [options] + +Build a package for production deployment or publishing Options: - --check Enable type checking and linting - --config <path> Config files to load instead of app-config.yaml (default: []) - -h, --help display help for command + --role <name> Run the command with an explicit package role + --minify Minify the generated code. Does not apply to app or backend packages. + --experimental-type-build Enable experimental type build. Does not apply to app or backend packages. + --skip-build-dependencies Skip the automatic building of local dependencies. Applies to backend packages only. + --stats If bundle stats are available, write them to the output directory. Applies to app packages only. + --config <path> Config files to load instead of app-config.yaml. Applies to app packages only. (default: []) ``` -## backend:build +## package lint -Scope: `backend-plugin` - -This builds a backend package for publishing and use in production. The build -output is written to `dist/`. Be sure to list any additional file that the -package depends on at runtime in the `"files"` field inside `package.json`, a -common example being the `migrations` directory. +Lint a package. In addition to the default `eslint` behavior, this command will +include TypeScript files, treat warnings as errors, and default to linting the +entire directory if no specific files are listed. For more information, see the +build system [linting](./cli-build-system.md#linting) section. ```text -Usage: backstage-cli backend:build [options] +Usage: backstage-cli package lint [options] + +Lint a package Options: - --minify Minify the generated code - -h, --help display help for command + --format <format> Lint report output format (default: "eslint-formatter-friendly") + --fix Attempt to automatically fix violations ``` -## backend:bundle +## package test -Scope: `backend` +Run tests, forwarding all unknown options to Jest, and defaulting to watch mode. +When executing the tests, `process.env.NODE_ENV` will be set to `"test"`. -Bundles the backend into a `dist/bundle.tar.gz` archive. See the -[backend bundling](./cli-build-system.md#backend-production-bundling) build -systems documentation for more details. +This command uses a default Jest configuration that is included in the CLI, +which is set up with similar goals for speed, scale, and working within a +monorepo. The configuration sets the `src` as the root directory, enforces the +`.test.` infix for tests, and uses `src/setupTests.ts` as the test setup +location. The included configuration also supports test execution at the root of +a yarn workspaces monorepo by automatically creating one grouped configuration +that includes all packages that have `backstage-cli test` in their package +`test` script. + +For more information about configuration overrides and editor support, see the [Jest Configuration section](./cli-build-system.md#jest-configuration) in the build system documentation. ```text -Usage: backstage-cli backend:bundle [options] +Usage: backstage-cli package test [options] -Bundle the backend into a deployment archive +Run tests, forwarding args to Jest, defaulting to watch mode Options: - --build-dependencies Build all local package dependencies before bundling the backend - -h, --help display help for command -``` - -## backend:build-image - -Scope: `backend` - -Builds a Docker image of the backend package, forwarding all unknown options to -`docker image build`. For example: - -```bash -yarn backstage-cli backend:build-image --build --tag my-backend-image -``` - -The image is built using the backend package along with all of its local package -dependencies. It expects to find a `Dockerfile` at the root of the backend -package, which will be used during the build. - -The Dockerfile is **NOT** executed within the package or repo itself. Because -the packages in the repo itself are configured for development instead of -production use, the final Docker build happens in a separate temporary -directory, to which the backend package and dependencies have been copied. Only -files listed within the `"files"` field within each package's `package.json` are -copied over, along with the root `package.json`, `yarn.lock`, and any -`app-config.*.yaml` files. - -During the build a `skeleton.tar` file is created and put at the repo root. This -file contains the `package.json` of each included package, which together with -the root `package.json` and `yarn.lock` can be used to run a cached -`yarn install` before the full production builds of all the packages are copied -over, providing a significant speedup if Docker build layer caching available. - -This command is experimental and we hope to be able to replace it with one that -is less integrated directly with Docker, and also supports multi-stage Docker -builds. It is possible to replicate most of what this command does by manually -building each package, and then use the `build-workspace` to create the -temporary workspace, and finally copy over any additional files to the workspace -and execute the Docker build within it. - -```text -Usage: backstage-cli backend:build-image [options] - -Options: - --build Build packages before packing them into the image --backstage-cli-help display help for command ``` -## backend:dev +## package clean -Scope: `backend`, `backend-plugin` - -Starts a backend package in development mode, with watch mode enabled for all -local dependencies. +Remove cache and output directories. ```text -Usage: backstage-cli backend:dev [options] +Usage: backstage-cli package clean [options] -Options: - --check Enable type checking and linting - --inspect Enable debugger - --config <path> Config files to load instead of app-config.yaml (default: []) - -h, --help display help for command +Delete cache directories +``` + +## package prepack + +This command should be added as `scripts.prepack` in all packages. It enables +packaging- and publish-time overrides for fields inside `packages.json`. +For more details, see the build system [publishing](./cli-build-system.md#publishing) section. + +```text +Usage: backstage-cli package prepack [options] + +Prepares a package for packaging before publishing +``` + +## package postpack + +This should be added as `scripts.postpack` in all packages. It restores +`package.json` to what it looked like before calling the `prepack` command. + +```text +Usage: backstage-cli package postpack [options] + +Restores the changes made by the prepack command ``` ## create -Scope: `root` - The `create` command opens up an interactive guide for you to create new things in your app. If you do not pass in any options it is completely interactive, but it is possible to pre-select what you want to create using the `--select` flag, @@ -278,181 +229,16 @@ this: Usage: backstage-cli create [options] Options: - --select Select the thing you want to be creating upfront - --option = Pre-fill options for the creation process (default: []) - --scope The scope to use for new packages - --npm-registry The package registry to use for new packages + --select <name> Select the thing you want to be creating upfront + --option <name>=<value> Pre-fill options for the creation process (default: []) + --scope <scope> The scope to use for new packages + --npm-registry <URL> The package registry to use for new packages --no-private Do not mark new packages as private -h, --help display help for command ``` -## create-plugin - -Scope: `root` - -Creates a new plugin within the repository. This command is typically wrapped up -in the root `package.json` to be executed with `yarn create-plugin`, using -options that are appropriate for the organization that owns the app repo. A -recommended scope for internal packages is `@internal`. - -```text -Usage: backstage-cli create-plugin [options] - -Options: - --backend Create plugin with the backend dependencies as default - --scope <scope> npm scope - --npm-registry <URL> npm registry URL - --no-private Public npm package - -h, --help display help for command -``` - -## remove-plugin - -Scope: `root` - -A utility to remove a plugin from a repo, essentially undoing everything that -was done by `create-plugin`. - -This is primarily intended as a utility for manual tests and end to end testing -scripts. - -```text -Usage: backstage-cli remove-plugin [options] - -Options: - -h, --help display help for command -``` - -## plugin:build - -Scope: `frontend-plugin` - -Build a frontend plugin for publishing to a package registry. There is no need -to run this command during development or even in CI unless the package is being -published. The `app:bundle` command does not use the output for this command -when bundling local package dependencies. - -The output is written to a `dist/` folder. It also outputs type declarations for -the plugin, and therefore requires `yarn tsc` to have been run first. The input -type declarations are expected to be found within `dist-types/` at the root of -the monorepo. - -```text -Usage: backstage-cli plugin:build [options] - -Options: - --minify Minify the generated code - -h, --help display help for command -``` - -## plugin:serve - -Scope: `frontend-plugin` - -Serves a frontend plugin by itself for isolated development. The serve task -itself is essentially identical to `app:serve`, but the entrypoint is instead -set to the `dev/` folder within the plugin. - -The `dev/` folder typically contains a small wrapper script that hooks up any -necessary mock APIs or other things that are needed for the plugin to function. -The `@backstage/dev-utils` package provides utilities to that end. - -```text -Usage: backstage-cli plugin:serve [options] - -Options: - --check Enable type checking and linting - --config <path> Config files to load instead of app-config.yaml (default: []) - -h, --help display help for command -``` - -## plugin:diff - -Scope: `frontend-plugin` - -Compares a frontend plugin to the `create-plugin` template, making sure that it -hasn't diverged from the template and recommending updates when it has. A good -practice is to run this command after updating the version of the CLI in a -project. - -```text -Usage: backstage-cli plugin:diff [options] - -Options: - --check Fail if changes are required - --yes Apply all changes - -h, --help display help for command -``` - -## build - -Scope: `any` - -Build a single package for publishing, just like the `plugin:build` and -`backend:build` commands. This command is intended for standalone packages that -aren't plugins, and for example support building of isomorphic packages for -usage in both the frontend and backend. - -For frontend packages you'll want to include `esm` output, and for backend -packages `cjs`. Whether to include `types` depends on if you need type -declarations for the package, and also requires `yarn tsc` to have been run -first. - -```text -Usage: backstage-cli build [options] - -Options: - --outputs <formats> List of formats to output [types,cjs,esm] - --minify Minify the generated code - -h, --help display help for command -``` - -## lint - -Scope: `any` - -Lint a package. In addition to the default `eslint` behavior, this command will -include TypeScript files, treat warnings as errors, and default to linting the -entire directory if no specific files are listed. - -```text -Usage: backstage-cli lint [options] - -Options: - --format <format> Lint report output format (default: "eslint-formatter-friendly") - --fix Attempt to automatically fix violations - -h, --help display help for command -``` - -## test - -Scope: `any` - -Run tests, forwarding all unknown options to Jest, and defaulting to watch mode. -When executing the tests, `process.env.NODE_ENV` will be set to `"test"`. - -This command uses a default Jest configuration that is included in the CLI, -which is set up with similar goals for speed, scale, and working within a -monorepo. The configuration sets the `src` as the root directory, enforces the -`.test.` infix for tests, and uses `src/setupTests.ts` as the test setup -location. The included configuration also supports test execution at the root of -a yarn workspaces monorepo by automatically creating one grouped configuration -that includes all packages that have `backstage-cli test` in their package -`test` script. - -For more information about configuration overrides and editor support, see the [Jest Configuration section](./cli-build-system.md#jest-configuration) in the build system documentation. - -```text -Usage: backstage-cli test [options] - -Options: - --backstage-cli-help display help for command -``` - ## config:docs -Scope: `root` - This commands opens up the reference documentation of your apps local configuration schema in the browser. This is useful to get an overview of what configuration values are available to use, a description of what they do and @@ -464,14 +250,12 @@ Usage: backstage-cli config:docs [options] Browse the configuration reference documentation Options: - --package Only include the schema that applies to the given package + --package <name> Only include the schema that applies to the given package -h, --help display help for command ``` ## config:print -Scope: `root` - Print the static configuration, defaulting to reading `app-config.yaml` in the repo root, using schema collected from all local packages in the repo. @@ -497,8 +281,6 @@ Options: ## config:check -Scope: `root` - Validate that static configuration loads and matches schema, defaulting to reading `app-config.yaml` in the repo root and using schema collected from all local packages in the repo. @@ -517,8 +299,6 @@ Options: ## config:schema -Scope: `root` - Dump the configuration schema that was collected from all local packages in the repo. @@ -538,8 +318,6 @@ Options: ## versions:bump -Scope: `root` - Bump all `@backstage` packages to the latest versions. This checks for updates in the package registry, and will update entries both in `yarn.lock` and `package.json` files when necessary. @@ -554,8 +332,6 @@ Options: ## versions:check -Scope: `root` - Validate `@backstage` dependencies within the repo, making sure that there are no duplicates of packages that might lead to breakages. @@ -571,63 +347,8 @@ Options: -h, --help display help for command ``` -## prepack - -Scope: `any` - -This command should be added as `scripts.prepack` in all packages. It enables -packaging- and publish-time overrides for fields inside `packages.json`. - -The checked in version of all packages in a Backstage monorepo are tailored for -local development, and as such `main` and similar fields inside `package.json` -point to development source, i.e. `src/index.ts`. Using this when publishing -would lead to a broken package, since `src/` is not included in the published -package and we instead need to point to files in the `dist/` directory. This -command allows for those fields to be rewritten when needed, and does so by -copying all fields within `publishConfig` to the top-level of each -`package.json`, skipping `access`, `registry`, and `tag`. - -The need for this command may be removed in the future, as this exact method of -overriding fields for publishing is already supported by some package managers. - -```text -Usage: backstage-cli prepack [options] - -Options: - -h, --help display help for command -``` - -## postpack - -Scope: `any` - -This should be added as `scripts.postpack` in all packages. It restores -`package.json` to what it looked like before calling the `prepack` command. - -```text -Usage: backstage-cli postpack [options] - -Options: - -h, --help display help for command -``` - -## clean - -Scope: `any` - -Remove cache and output directories. - -```text -Usage: backstage-cli clean [options] - -Options: - -h, --help display help for command -``` - ## build-workspace -Scope: `any`, `root` - Builds a mirror of the workspace using the packaged production version of each package. This essentially calls `yarn pack` in each included package and unpacks the resulting archive in the target `workspace-dir`. @@ -638,8 +359,6 @@ Usage: backstage-cli build-workspace [options] <workspace-dir> ## create-github-app -Scope: `root` - Creates a GitHub App in your GitHub organization. This is an alternative to token-based [GitHub integration](../integrations/github/locations.md). See [GitHub Apps for Backstage Authentication](../plugins/github-apps.md). @@ -653,8 +372,6 @@ Usage: backstage-cli create-github-app <github-org> ## info -Scope: `root` - Outputs debug information which is useful when opening an issue. Outputs system information, node.js and npm versions, CLI version and type (inside backstage repo or a created app), all `@backstage/*` package dependency versions.