Standing Up Backstage

40 MINS

Backstage app structure

The Backstage app is set up as a monorepo. This means that the app is composed of many small, isolated packages that could be in separate repositories or folders entirely, but have been joined into a single structure for convenience.

For example, your Backstage app now contains a packages directory with two packages — app and backend. Each of these has its own package.json, declaring dependencies and yarn commands only for that package. These packages are brought together using Lerna and Yarn workspaces.

Folder structure

The folder structure created for your installed Backstage app looks roughly like this:

rockitengine
└─ packages
    ├─ app
    └─ backend
├─ app-config.yaml
├─ catalog-info.yaml
├─ lerna.json
└─ package.json

There are two packages created by default: app and backend. Installing new Backstage plugins will often require small tweaks to the files in these packages.

  • app: This is the React frontend for your Backstage app. It contains the root index.html that will get loaded when someone visits your app, and the minimal source code to customize the interface.
  • backend: This is the Express backend for your Backstage app that talks to the database and has a REST API that the frontend fetches data from.

There are a few other files to note in the root directory. Take a look:

app-config.yaml

This is the configuration file for your Backstage app. This is where you can customize the application name shown in the UI, your company name, and many other features of Backstage.

catalog-info.yaml

This is a file that the Backstage Software Catalog uses to keep track of software in your organization. These metadata descriptor files follow the Kubernetes object format, and will generally live alongside any software you want to track in Backstage — including Backstage itself! So meta.

lerna.json

Lerna helps link your packages together in a monorepo, so they can depend on each other. This file tells Lerna where to look for packages — namely, the packages directory we see already, and a plugins directory that won’t exist until you create your first custom plugin.

package.json

The root npm package declaration for the entire monorepo. Note that you generally should not be adding npm package dependencies here, but instead in one of the sub-packages that needs the dependency (e.g. app or backend).