paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 21 Packages Projects Releases Wiki Activity

docs/cli: text fixes

Browse Source
This commit is contained in:
Patrik Oldsberg
2020-12-13 19:48:22 +01:00
parent e0426d00ed
commit 436202b20e
2 changed files with 108 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/cli/commands.md
+62 -62
View File
@@ -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 <path> Config files to load instead of app-config.yaml (default: [])
--config &lt;path&gt; 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 <path> Config files to load instead of app-config.yaml (default: [])
--config &lt;path&gt; 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 <path> Config files to load instead of app-config.yaml (default: [])
--config &lt;path&gt; 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 <scope> npm scope
--npm-registry <URL> npm registry URL
--scope &lt;scope&gt; npm scope
--npm-registry &lt;URL&gt; 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 <path> Config files to load instead of app-config.yaml (default: [])
--config &lt;path&gt; 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 <formats> List of formats to output [types,cjs,esm]
--outputs &lt;formats&gt; 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 <format> Lint report output format (default: "eslint-formatter-friendly")
--format &lt;format&gt; 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 <name> Only load config schema that applies to the given package
--package &lt;name&gt; 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> Format to print the configuration in, either json or yaml [yaml]
--config <path> Config files to load instead of app-config.yaml (default: [])
--format &lt;format&gt; Format to print the configuration in, either json or yaml [yaml]
--config &lt;path&gt; 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 <name> Only load config schema that applies to the given package
--config <path> Config files to load instead of app-config.yaml (default: [])
--package &lt;name&gt; Only load config schema that applies to the given package
--config &lt;path&gt; 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] <workspace-dir>
Usage: backstage-cli build-workspace [options] &lt;workspace-dir&gt;
Options:
```
docs/cli/index.md
+46 -35
View File
@@ -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 <command>` 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 <command>` 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