Skip to main content

001 - Scaffolding

Audience: Developers and Admins

Note

It is not required, although recommended to have a basic understanding of Yarn and npm before starting this guide.

Summary​

This guide walks through how to get started creating your very own Backstage customizable app. This is the first step in evaluating, developing on, or demoing Backstage.

By the end of this guide, you will have a standalone Backstage installation running locally with a SQLite database and demo content.

Organization customization

To be clear, this is not a production-ready installation, and it does not contain information specific to your organization. You will learn how to customize Backstage for your use case through this guide.

Prerequisites​

This guide also assumes a basic understanding of working on a Linux based operating system and have some experience with the terminal, specifically, these commands: npm, yarn.

Scaffold your new Backstage app​

1. Create your Backstage App​

To scaffold your new Backstage app, we'll be running an interactive command. Before you run the command, you should open a terminal and move your current working directory somewhere you're comfortable creating a new directory.

The wizard for this command will ask what name you want to have for your new app. That name will match the folder that we create for you.

When you run the command, you'll see an output like this.

create app

And when it finishes, you'll have a working Backstage app (with example data)!

Now, that we know what it does, let's actually scaffold some code!

npx @backstage/create-app@latest

This may take a few minutes to fully install everything. Don't stress if the loading seems to be spinning nonstop, there's a lot going on in the background.

note

If this fails on the yarn install step, it's likely that you will need to install some additional dependencies which are used to configure isolated-vm. You can find out more in their requirements section, and then run yarn install manually again after you've completed those steps.

Structure of your app​

General folder structure​

Below is a simplified layout of the files and folders generated when creating an app.

app
├── app-config.yaml
├── catalog-info.yaml
├── package.json
└── packages
    ├── app
    └── backend
  • app-config.yaml: Main configuration file for the app. See Configuration for more information.
  • catalog-info.yaml: Catalog Entities descriptors. See Descriptor Format of Catalog Entities to get started.
  • package.json: Root package.json for the project. Note: Be sure that you don't add any npm dependencies here as they probably should be installed in the intended workspace rather than in the root.
  • packages/: Lerna leaf packages or "workspaces". Everything here is going to be a separate package, managed by lerna.
  • packages/app/: A fully functioning Backstage frontend app that acts as a good starting point for you to get to know Backstage.
  • packages/backend/: We include a backend that helps power features such as Authentication, Software Catalog, Software Templates and TechDocs amongst other things.

Common Issues​

  • App is not running on port X: Backstage uses ports 3000 and 7007 as its default frontend and backend ports. Make sure that your commands haven't exited with errors. For remote or containerized setups, make sure those ports above are accessible.

Next Steps​

Now that you have a scaffolded app, let's learn how to start it locally for development!