Backstage Backend Plugin (New Backend System)

About This Skill

This skill provides specialized knowledge and workflows for building Backstage backend plugins using the New Backend System. It guides the development of server-side functionality including REST/HTTP APIs, background jobs, data processing, and integrations.

What This Skill Provides

1. Specialized workflows - Step-by-step procedures for creating and configuring backend plugins
2. Best practices - Production-ready patterns for auth, validation, error handling, and database usage
3. Golden path templates - Copy/paste code snippets for common backend patterns
4. Domain expertise - Backstage-specific knowledge about DI, core services, and secure-by-default architecture

When to Use This Skill

Use this skill when creating server-side functionality for Backstage: REST/HTTP APIs, background jobs, data processing, or integrations.

Development Workflow

Phase 1: Planning and Research

1.1 Understand the Requirements

Before building a backend plugin, clearly understand:

• What endpoints or APIs are needed (REST, GraphQL, webhooks)
• What data storage requirements exist (database, cache)
• Whether background jobs or scheduled tasks are needed
• Authentication and authorization requirements
• Integration points with other services or plugins

1.2 Load Reference Documentation

Load reference files as needed based on the plugin requirements:

For Core Services:

• ⚙️ Core Services Reference - Comprehensive guide to all core backend services including:
  • httpRouter, logger, database, httpAuth, userInfo
  • cache, scheduler, urlReader, discovery, permissions
  • Usage patterns and best practices for each service

For Testing:

• ✅ Testing Reference - Comprehensive testing guide for backend plugins

Phase 2: Implementation

Follow the Golden Path workflow below for implementation, referring to reference files as needed.

Important Decisions:

• Determine which core services are needed (load ⚙️ Core Services Reference)
• Plan database schema and migrations if using database
• Design authentication policies (which endpoints need auth?)
• Plan error handling and validation strategies

Phase 3: Testing

After implementing the plugin:

1. Load the ✅ Testing Reference
2. Write comprehensive tests for:
   • Router endpoints using

     startTestBackend

   • Database operations with

     TestDatabases

   • External service calls with MSW (Mock Service Worker)
   • Authentication flows
3. Run tests and achieve good coverage:

   yarn backstage-cli package test --coverage
   

Phase 4: Review and Polish

Before publishing:

1. Run linting and structure checks
2. Ensure proper error handling throughout
3. Verify authentication policies are correct
4. Check database migrations are production-ready
5. Review the Common Pitfalls section below
6. Test horizontal scalability (no in-memory state)

Quick Facts

• Scaffold with

  yarn new

  → backend‑plugin; the package lives in

  plugins/<id>-backend/

  .
• Define the plugin with

  createBackendPlugin

  , declare dependencies via

  deps

  , and initialize in

  register(env).registerInit

  .
• Attach routes through

  coreServices.httpRouter

  . Backstage prefixes plugin routers with

  /api/<pluginId>

  .
• Backends are secure by default; use

  httpRouter.addAuthPolicy({ path, allow })

  to allow unauthenticated endpoints like

  /health

  .
• Core services (logger, database, httpRouter, httpAuth, userInfo, urlReader, scheduler, etc.) are available via

  coreServices

  .

Production Best Practices

Request Validation

Validate inputs at the edge using a schema (e.g., zod) before hitting DBs or external services:

import { z } from 'zod';
const querySchema = z.object({ q: z.string().min(1) });
router.get('/search', async (req, res, next) => {
  const parsed = querySchema.safeParse(req.query);
  if (!parsed.success) return res.status(400).json({ error: 'invalid query' });
  try {
    // ... perform work with parsed.data.q
    res.json({ items: [] });
  } catch (e) { next(e); }
});

Error Handling

Add a terminal error handler to your router and prefer structured logs with context:

import { errorHandler } from '@backstage/backend-common';
router.use(errorHandler());

Auth and Identity

• Keep backends secure-by-default

• Open only explicit paths with

  addAuthPolicy

• For protected routes, extract credentials with

  httpAuth

• Derive user/entity identity via

  userInfo

  when required

  // Inside a route handler
  const creds = await httpAuth.credentials(req, { allow: ['user', 'service'] });
  const { userEntityRef } = await userInfo.getUserInfo(creds);
  logger.info('request', { userEntityRef });
  

Database Usage

• Use

  const knex = await database.getClient();

  to get a database client
• Keep queries in small repo/service modules
• Write migrations in JavaScript (

  .js

  ) and export them in package.json (see Core Services Reference for details)

Observability & Scalability

• Avoid in-memory state
• Make handlers idempotent
• Log with

  logger.child({ plugin: 'example' })

  for traceability

Golden Path (Copy/Paste Workflow)

1) Scaffold

# From the repository root (interactive)
yarn new
# Select: backend-plugin
# Plugin id (without -backend suffix), e.g. example

# Non-interactive (for AI agents/automation)
yarn new --select backend-plugin --option pluginId=example --option owner=""

This creates

plugins/example-backend/

createBackendPlugin

(Backstage)

2)

src/plugin.ts

— plugin + DI + router

import { createBackendPlugin, coreServices } from '@backstage/backend-plugin-api';
import { createRouter } from './service/router';

export const examplePlugin = createBackendPlugin({
  pluginId: 'example',
  register(env) {
    env.registerInit({
      deps: {
        httpRouter: coreServices.httpRouter,
        logger: coreServices.logger,
        database: coreServices.database,     // optional
        httpAuth: coreServices.httpAuth,     // optional
        userInfo: coreServices.userInfo,     // optional
      },
      async init({ httpRouter, logger, database, httpAuth, userInfo }) {
        const router = await createRouter({ logger, database, httpAuth, userInfo });
        httpRouter.use(router);

        // Secure-by-default: open /health only
        httpRouter.addAuthPolicy({ path: '/health', allow: 'unauthenticated' });
      },
    });
  },
});

export { examplePlugin as default } from './plugin';

Key points: DI via

deps

httpRouter

3)

src/service/router.ts

— minimal Express router

import express from 'express';
import type {
  LoggerService,
  DatabaseService,
  HttpAuthService,
  UserInfoService,
} from '@backstage/backend-plugin-api';

export interface RouterOptions {
  logger: LoggerService;
  database?: DatabaseService;
  httpAuth?: HttpAuthService;
  userInfo?: UserInfoService;
}

export async function createRouter(options: RouterOptions): Promise<express.Router> {
  const { logger } = options;
  const router = express.Router();

  router.get('/health', (_req, res) => {
    logger.info('health check');
    res.json({ status: 'ok' });
  });

  return router;
}

4) Add to your backend

In

packages/backend/src/index.ts

const backend = createBackend();
backend.add(import('@internal/plugin-example-backend'));
backend.start();

Now

GET http://localhost:7007/api/example/health

{ "status": "ok" }

5) Database, auth, identity (when needed)

• Database: depend on

  coreServices.database

  to get a Knex client; create your own migrations and run them via your chosen process. (Backstage)
• Identity: use

  coreServices.httpAuth

  +

  coreServices.userInfo

  to obtain the calling user and their entity refs when an endpoint needs identity. (Backstage)
• Core services catalog: consult the Backstage Core Backend Service APIs for the full list (cache, scheduler, urlReader, etc.). (Backstage)

Verify in a Backstage backend

• Add the plugin to

  packages/backend/src/index.ts

  via

  backend.add(import('@internal/plugin-<id>-backend'))

  .
• Start the repo (e.g.,

  yarn start

  at the root). Then check:
  • GET http://localhost:7007/api/example/health →

    { "status": "ok" }

  • If 401 occurs, ensure you opened

    /health

    with

    addAuthPolicy

    .

Testing, linting & structure checks

Use Backstage's CLI for tests and lints:

yarn backstage-cli package test
yarn backstage-cli package lint
yarn backstage-cli repo lint

Keep routers small (

/service/router.ts

plugin.ts

Common Pitfalls (and Fixes)

/api

/api/<pluginId>

httpRouter.addAuthPolicy

Reference Files

📚 Documentation Library

Load these resources as needed during development:

Core Services

• ⚙️ Core Services Reference - Complete guide to all core backend services including:
  • HTTP Router Service for route registration
  • Logger Service for structured logging
  • Database Service for Knex-based data access
  • HTTP Auth Service and User Info Service for authentication
  • Cache Service for key-value storage
  • Scheduler Service for background tasks
  • Discovery Service for inter-plugin communication
  • URL Reader Service for reading external content
  • Permissions Service for authorization
  • Configuration and health check services
  • Service composition examples and best practices

Testing

• ✅ Testing Reference - Comprehensive testing guide including:
  • Testing backend plugins with

    startTestBackend

  • Mock services for all core services
  • Testing routers with supertest
  • Testing authentication and permissions
  • External service mocking with MSW
  • Database testing with

    TestDatabases

  • Service factory testing
  • Integration testing patterns
  • Best practices and common patterns

External References

• Backend plugins: scaffolding, DI,

  httpRouter

  ,

  /api/<pluginId>

  , secure‑by‑default, DB & identity usage. (Backstage)
• Core Backend Service APIs index (logger, database, httpAuth, scheduler, urlReader, etc.). (Backstage)
• Anthropic Skill spec & packaging details (required metadata; ≤200 char description). (Claude Help Center)