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