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

docs: merge build system docs with cli docs + restructure

Browse Source 
Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
This commit is contained in:
Patrik Oldsberg
2022-01-17 09:58:36 +01:00
parent 6bc3d749e8
commit d5f3d84817
5 changed files with 82 additions and 139 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/local-dev/cli-build-system.md
+55 -56
View File
@@ -4,8 +4,6 @@ title: Build System
description: A deep dive into the Backstage build system
---
## What is the Backstage build system?
The Backstage build system is a collection of build and development tools that
help you lint, test, develop and finally release your Backstage projects. The
purpose of the build system is to provide an out-of-the-box solution that works
@@ -43,6 +41,7 @@ In addition, there are a number of hard and soft requirements:
- Simple - Usage should simple and configuration should be kept minimal
- Universal - Development towards both web applications, isomorphic packages,
and Node.js
- Modern - The build system targets modern environments
- Editors - Type checking and linting should be available within most editors
During the design of the build system this collection of requirements was not
@@ -50,7 +49,7 @@ something that was supported by existing tools like for example `react-scripts`.
The requirements of scaling in combination of monorepo, publishing, and editor
support led us to adopting our own specialized setup.
## Architecture
## Structure
We can divide the development flow within Backstage into a couple of different
steps:
@@ -73,7 +72,7 @@ or IDE that has support for formatting, linting, and type checking.
Let's dive into a detailed look at each of these steps and how they are
implemented in a typical Backstage app.
### Formatting
## Formatting
The formatting setup lives completely within each Backstage application and is
not part of the CLI. In an app created with `@backstage/create-app` the
@@ -81,7 +80,7 @@ formatting is handled by [prettier](https://prettier.io/), but each application
can those their own formatting rules and switch to a different formatter if
desired.
### Linting
## Linting
The Backstage CLI includes a `lint` command, which is a thin wrapper around
`eslint`. It adds a few options that can't be set through configuration, such as
@@ -101,7 +100,7 @@ the entire project. Each configuration is initially one that simply extends a
base configuration provided by the Backstage CLI, but they can be customized to
fit the needs of each package.
### Type Checking
## Type Checking
Just like formatting, the Backstage CLI does not have its own command for type
checking. It does however have a base configuration with both recommended
@@ -135,7 +134,7 @@ through the `tsc:full` script, which will run a full type check, including
For the two reasons mentioned above, it is **highly** recommended to use the
`tsc:full` script to run type checking in CI.
### Testing
## Testing
As mentioned above, the Backstage CLI uses [Jest](https://jestjs.io/), which is
a JavaScript test framework that covers both test execution and assertions. Jest
@@ -158,7 +157,7 @@ configuration, as well as allowing for configuration overrides to be defined in
each `package.json`. How this can be done in practice is discussed in the
[Jest configuration](#jest-configuration) section.
### Building
## Building
The primary purpose of the build process is to prepare packages for publishing,
but it's also used as part of the backend bundling process. Since it's only used
@@ -199,14 +198,14 @@ that are exported from the package, leaving a much cleaner type definition file
and making sure that the type definitions are in sync with the generated
JavaScript.
### Bundling
## Bundling
The goal of the bundling process is to combine multiple packages together into a
single runtime unit. The way this is done varies between frontend and backend,
as well as local development versus production deployment. Because of that we
cover each combination of these cases separately.
#### Frontend Development Bundling
### Frontend Development
There are two different commands that starts the frontend development bundling,
`app:serve`, which serves an app and uses `src/index` as the entrypoint, and
@@ -233,7 +232,7 @@ by passing the `--check` flag. Although as mentioned above, the recommended way
to handle these checks during development is to use an editor that has built-in
support for them instead.
#### Frontend Production Bundling
### Frontend Production
The frontend production bundling creates your typical web content bundle, all
contained within a single folder, ready for static serving. It is invoked using
@@ -277,7 +276,7 @@ changes to individual plugins and packages will invalidate a smaller number of
files, thereby allowing for rapid development without much impact on the page
load performance.
#### Backend Development Bundling
### Backend Development
The backend development bundling is also based on Webpack, but rather than
starting up a web server, the backend is started up using the
@@ -300,7 +299,7 @@ If you want to inspect the running Node.js process, the `--inspect` and
`--inspect-brk` flags can be used, as they will be passed through as options to
`node` execution.
#### Backend Production Bundling
### Backend Production
The backend production bundling uses a completely different setup than the other
bundling options. Rather than using Webpack, the backend production bundling
@@ -419,49 +418,6 @@ of all supported file extensions:
| `.svg` | URL Path | Image |
| `.icon.svg` | React Component | SVG converted into a [MUI SvgIcon](https://mui.com/components/icons/#svgicon) |
## Publishing
Package publishing is an optional part of the Backstage build system and not
something you well need to worry unless you are publishing packages to a
registry. In order to publish a package, you first need to build it, which will
populate the `dist` folder. Because the Backstage build system is optimized for
local development along with our particular TypeScript and bundling setup, it is
not possible to publish package immediately at this point. This is because the
entry points of the package will still be pointing to `src/index.ts`, but we
want them to point to `dist/` in the published package.
In order to work around this, the Backstage CLI provides `prepack` and
`postpack` commands that help prepare the package for publishing. These scripts
are automatically run by Yarn before publishing a package.
The `prepack` command will take entry point fields in `"publishConfig"`, such
as, `"main"` and `"module"`, and move the top level of the `package.json`. This
lets you point at the desired files in the `dist` folder during publishing. The
`postpack` command will simply revert this change in order to leave your project
clean.
The following is an excerpt of a typical setup of an isomorphic library package:
```json
"main": "src/index.ts",
"types": "src/index.ts",
"publishConfig": {
"access": "public",
"main": "dist/index.cjs.js",
"module": "dist/index.esm.js",
"types": "dist/index.d.ts"
},
"scripts": {
"build": "backstage-cli build",
"lint": "backstage-cli lint",
"test": "backstage-cli test",
"prepack": "backstage-cli prepack",
"postpack": "backstage-cli postpack",
"clean": "backstage-cli clean"
},
"files": ["dist"],
```
## Jest Configuration
The Backstage CLI bundles its own Jest configuration file, which is used
@@ -507,3 +463,46 @@ The overrides in a single `package.json` may for example look like this:
}
},
```
## Publishing
Package publishing is an optional part of the Backstage build system and not
something you well need to worry unless you are publishing packages to a
registry. In order to publish a package, you first need to build it, which will
populate the `dist` folder. Because the Backstage build system is optimized for
local development along with our particular TypeScript and bundling setup, it is
not possible to publish package immediately at this point. This is because the
entry points of the package will still be pointing to `src/index.ts`, but we
want them to point to `dist/` in the published package.
In order to work around this, the Backstage CLI provides `prepack` and
`postpack` commands that help prepare the package for publishing. These scripts
are automatically run by Yarn before publishing a package.
The `prepack` command will take entry point fields in `"publishConfig"`, such
as, `"main"` and `"module"`, and move the top level of the `package.json`. This
lets you point at the desired files in the `dist` folder during publishing. The
`postpack` command will simply revert this change in order to leave your project
clean.
The following is an excerpt of a typical setup of an isomorphic library package:
```json
"main": "src/index.ts",
"types": "src/index.ts",
"publishConfig": {
"access": "public",
"main": "dist/index.cjs.js",
"module": "dist/index.esm.js",
"types": "dist/index.d.ts"
},
"scripts": {
"build": "backstage-cli build",
"lint": "backstage-cli lint",
"test": "backstage-cli test",
"prepack": "backstage-cli prepack",
"postpack": "backstage-cli postpack",
"clean": "backstage-cli clean"
},
"files": ["dist"],
```
docs/local-dev/cli-commands.md
+1 -1
View File
@@ -1,6 +1,6 @@
---
id: cli-commands
title: CLI Commands
title: Commands
description: Descriptions of all commands available in the CLI.
---
docs/local-dev/cli-overview.md
+24 -80
View File
@@ -1,97 +1,41 @@
---
id: cli-overview
title: CLI Overview
title: Overview
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`](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,
[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.
For a full list of CLI commands, see the [commands](./cli-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`](https://www.npmjs.com/package/@backstage/cli) package.
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:
```text
yarn backstage-cli --help
```
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
minimal. As a part of accomplishing this goal, Backstage provides its own build
system and tooling, delivered primarily through the
[`@backstage/cli`](https://www.npmjs.com/package/@backstage/cli) package. When
creating an app using
[`@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.
you receive a project that's already prepared with a typical setup and package
scripts for executing the most common commands.
## Opinionated Tooling
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 tooling for working within Backstage apps, for example
for keeping the app up to date and verifying static configuration. For a more
in-depth look info the tooling, see the [build system](./cli-build-system.md)
page, and for a list of commands, see the [commands](./cli-commands.md) page.
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 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 it works, 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
quite standard combination of transpiled JavaScript and TypeScript type
declarations. The usage of the command from the CLI can therefore be augmented
or replaced with other tools if necessary.
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 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. This allows us
to quickly iterate and improve the tooling, as well as to more easily keep
dependencies up to date.
## 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 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.
- 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 technologies such as HTTP/2 to optimize frontend speed.
The Backstage CLI intentionally 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 iterate and
improve the tooling, as well as to more easily keep the system up to date.
## Glossary
microsite/sidebars.json
+1 -1
View File
@@ -34,7 +34,7 @@
{
"type": "subcategory",
"label": "CLI",
"ids": ["local-dev/cli-overview", "local-dev/cli-commands", "local-dev/cli-build-system"]
"ids": ["local-dev/cli-overview", "local-dev/cli-build-system", "local-dev/cli-commands"]
},
"local-dev/linking-local-packages"
],
mkdocs.yml
+1 -1
View File
@@ -30,8 +30,8 @@ nav:
- Local Development:
- CLI:
- Overview: 'local-dev/cli-overview.md'
- Commands: 'local-dev/cli-commands.md'
- Build System: 'local-dev/cli-build-system.md'
- Commands: 'local-dev/cli-commands.md'
- Linking in Local Packages: 'local-dev/linking-local-packages.md'
- Core Features:
- Software Catalog: