How to Set Up Backstage for a Node.js Project

4 min readJul 16, 2024

Backstage is an open-source framework for building developer portals. Powered by a centralized software catalog, Backstage restores order to your microservices and infrastructure, enabling your product teams to ship high-quality code quickly without compromising autonomy. It unifies all your infrastructure tooling, services, and documentation to create a streamlined development environment from end to end.

For setting up your project in Backstage, you need to have a Backstage app.

Steps to Create a Backstage App

Create a New Backstage App

Run this command:

npx @backstage/create-app@latest

2. General Folder Structure

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: Ensure that you don't add any npm dependencies here as they 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/: Backend that powers features such as Authentication, Software Catalog, Software Templates, and TechDocs, among others.

Step 2: Customize the `app-config.yaml` File

Add PostgreSQL database credentials and other configuration details:

app:
  title: Medium Documentation
  baseUrl: http://localhost:3000

organization:
  name: Medium

backend:
  # Used for enabling authentication, secret is shared by all backend plugins
  # See https://backstage.io/docs/auth/service-to-service-auth for
  # information on the format
  # auth:
  #   keys:
  #     - secret: ${BACKEND_SECRET}
  baseUrl: http://localhost:7007
  listen:
    port: 7007
    # Uncomment the following host directive to bind to specific interfaces
    # host: 127.0.0.1
  csp:
    connect-src: ["'self'", 'http:', 'https:']
    # Content-Security-Policy directives follow the Helmet format: https://helmetjs.github.io/#reference
    # Default Helmet Content-Security-Policy values can be removed by setting the key to false
  cors:
    origin: http://localhost:3000
    methods: [GET, HEAD, PATCH, POST, PUT, DELETE]
    credentials: true
  # This is for local development only, it is not recommended to use this in production
  # The production database configuration is stored in app-config.production.yaml
  database:
    client: pg
    connection:
      host: localhost
      port: 5432
      user: <username>
      password: <password>
      database: backstage
  # workingDirectory: /tmp # Use this to configure a working directory for the scaffolder, defaults to the OS temp-dir

integrations:
  github:
    - host: github.com
      # This is a Personal Access Token or PAT from GitHub. You can find out how to generate this token, and more information
      # about setting up the GitHub integration here: https://backstage.io/docs/integrations/github/locations#configuration
      token: <github-token>
    ### Example for how to add your GitHub Enterprise instance using the API:
    # - host: ghe.example.net
    #   apiBaseUrl: https://ghe.example.net/api/v3
    #   token: ${GHE_TOKEN}

proxy:
  ### Example for how to add a proxy endpoint for the frontend.
  ### A typical reason to do this is to handle HTTPS and CORS for internal services.
  # endpoints:
  #   '/test':
  #     target: 'https://example.com'
  #     changeOrigin: true
# Reference documentation http://backstage.io/docs/features/techdocs/configuration
# Note: After experimenting with basic setup, use CI/CD to generate docs
# and an external cloud storage when deploying TechDocs for production use-case.
# https://backstage.io/docs/features/techdocs/how-to-guides#how-to-migrate-from-techdocs-basic-to-recommended-deployment-approach

auth:
  # see https://backstage.io/docs/auth/ to learn about auth providers
  providers:
    # See https://backstage.io/docs/auth/guest/provider
    guest: {}

scaffolder:
  # see https://backstage.io/docs/features/software-templates/configuration for software template options

catalog:
  import:
    entityFilename: catalog-info.yaml
    pullRequestBranchName: backstage-integration
  rules:
    - allow: [Component, API, System, Domain, Resource, Location, User, Group]
  locations:
    - type: url
      target: https://github.com/backstage/software-templates/blob/main/scaffolder-templates/react-ssr-template/template.yaml
      rules:
        - allow: [Template]
    - type: file
      target: template.yaml 
    # Add your GitHub location here
    ## Uncomment these lines to add more example data
    # - type: url
    #   target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/all.yaml

    ## Uncomment these lines to add an example org
    # - type: url
    #   target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/acme-corp.yaml
    #   rules:
    #     - allow: [User, Group]

Step 3: Run the Backstage App

Start the frontend and backend:

# start frontend
yarn start

# start backend
yarn start-backend

It will look something like this:-

Registering Your First Entity in Backstage

To register an entity in Backstage, create a catalog-info.yaml file in the root directory of your project. This file helps to show the relations, APIs, dependencies, and ownership.

Here is a sample catalog-info.yaml file:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-awesome-service
  description: My awesome service description
spec:
  type: service
  lifecycle: production
  owner: medium