Edit

Overview

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 package.json scripts. When creating an app using @backstage/create-app it contains package scripts for executing the most common commands.

Under the hood the CLI uses Webpack for bundling, Rollup for building packages, Jest for testing, and eslint 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 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.

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:

yarn backstage-cli --help

If you are familiar with create-react-app you may recognize the pattern of bundling tooling up as a CLI, 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, as well as tooling that is more unique to Backstage, such as commands for working with static configuration.

Opinionated Tooling

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 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.

Glossary

• Package - A package in the Node.js ecosystem, often published to a package registry such as NPM.
• 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 and yarn 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.