Backstage Backend Plugin (New Backend System)

About This Skill

This skill provides specialized knowledge and workflows for building Backstage backend plugins and modules using the New Backend System. It guides the development of server-side functionality including REST/HTTP APIs, background jobs, data processing, and integrations, plus the module/extension-point pattern used to extend other plugins.

What This Skill Provides

1. Specialized workflows - Step-by-step procedures for creating and configuring backend plugins and modules
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, integrations, or modules that extend an existing plugin's extension points.

---

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
• Whether you're writing a plugin (new surface area) or a module (extending another plugin's extension points)
• 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, auth
  • cache, scheduler, urlReader, discovery, permissions, permissionsRegistry
  • auditor, lifecycle, rootHealth, rootConfig, rootInstanceMetadata
  • 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, if any, should be unauthenticated?)
• Plan error handling and validation strategies
• Decide whether extension points are needed so other teams can extend this plugin

---

Phase 3: Testing

After implementing the plugin:

1. Load the ✅ Testing Reference
2. Write comprehensive tests for:
   • Plugin/module integration via startTestBackend
   • Router endpoints using supertest against the test server
   • Database operations with TestDatabases
   • External service calls with MSW (v2 API)
   • Authentication flows using mockCredentials and mockServices.httpAuth.mock
3. Run tests and achieve good coverage:

   yarn backstage-cli package test --coverage --watchAll=false
   

---

Phase 4: Review and Polish

Before publishing:

1. Run linting and structure checks
2. Ensure proper error handling throughout — let errors bubble up so the root HTTP router's error middleware formats them
3. Verify authentication policies are correct (backends are secure by default)
4. Check database migrations are production-ready and written in JavaScript
5. Review the Common Pitfalls section below
6. Test horizontal scalability (no in-memory state; use the cache or database services)

---

Quick Facts

• Scaffold with yarn new → select 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.
• allow on addAuthPolicy only accepts 'unauthenticated' or 'user-cookie'.
• Core services (logger, database, httpRouter, httpAuth, auth, userInfo, urlReader, scheduler, cache, permissions, etc.) are available via coreServices.
• Validate inputs with zod and throw InputError from @backstage/errors. Let the root HTTP router handle error responses — you usually don't need per-router error middleware.
• A module (createBackendModule) extends another plugin via its extension points. A plugin exposes extension points with env.registerExtensionPoint(...).

---

Production Best Practices

Request Validation

Validate inputs at the edge using zod. Throw InputError (from @backstage/errors) on failure so the root error handler can serialize it as a 400 response — no need to write the response yourself:

import { InputError } from '@backstage/errors';
import { z } from 'zod/v3';

const querySchema = z.object({ q: z.string().min(1) });

router.get('/search', async (req, res) => {
  const parsed = querySchema.safeParse(req.query);
  if (!parsed.success) {
    throw new InputError(parsed.error.toString());
  }
  const results = await search(parsed.data.q);
  res.json({ items: results });
});

Use zod/v3 (or zod/v4 — both are available in the repo today) to pin behaviour across the codebase. Recent scaffolded plugins use zod/v3.

Error Handling

The root HTTP router installs a centralized error middleware, so individual plugin routers don't need to add their own. If you need to customize error formatting at the root level, use MiddlewareFactory from @backstage/backend-defaults/rootHttpRouter:

import { MiddlewareFactory } from '@backstage/backend-defaults/rootHttpRouter';

// Typically only set up once in tests or at the root.
const middleware = MiddlewareFactory.create({ config, logger });
router.use(middleware.error({ logAllErrors: false }));

The legacy helper errorHandler from @backstage/backend-common has been removed. Use MiddlewareFactory.create(...).error(), or mockErrorHandler from @backstage/backend-test-utils in tests.

Wrap async handlers with express-promise-router so thrown errors reach the error middleware automatically — that's what the scaffolded template does.

Auth and Identity

• Backends are secure-by-default
• Open specific paths explicitly with httpRouter.addAuthPolicy({ path, allow: 'unauthenticated' })
• For protected routes, extract credentials with httpAuth
• Derive user/entity identity via userInfo when required
• Use auth to issue on-behalf-of tokens for calls to other plugins

router.get('/me', async (req, res) => {
  const credentials = await httpAuth.credentials(req, { allow: ['user'] });
  const { userEntityRef, ownershipEntityRefs } = await userInfo.getUserInfo(credentials);
  res.json({ userEntityRef, ownershipEntityRefs });
});

Database Usage

• const knex = await database.getClient(); gets a per-plugin Knex client (separate schema per plugin)
• Keep queries in small repo/service modules
• Write migrations in JavaScript (.js) and include them in your package's files list
• Run migrations via knex.migrate.latest({ directory, migrationSource }) during init

Observability & Scalability

• Avoid in-memory state — use the cache or database services so multiple replicas share state
• Make scheduled task handlers idempotent
• Log with logger.child({ plugin: 'example' }) for traceability
• For auditing, use coreServices.auditor to emit structured audit events

---

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/ using the New Backend System. The scaffolded structure is:

• src/plugin.ts — createBackendPlugin wiring
• src/router.ts — Express router (uses express-promise-router)
• src/services/ — service refs + implementations
• src/index.ts — re-exports the plugin as default
• dev/index.ts — local dev backend via createBackend
• src/plugin.test.ts — integration tests using startTestBackend + supertest

2) src/plugin.ts — plugin + DI + router

The scaffolded shape wires in a service ref (e.g. todoListServiceRef) alongside core services:

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

export const examplePlugin = createBackendPlugin({
  pluginId: 'example',
  register(env) {
    env.registerInit({
      deps: {
        httpAuth: coreServices.httpAuth,
        httpRouter: coreServices.httpRouter,
        todoList: todoListServiceRef,
      },
      async init({ httpAuth, httpRouter, todoList }) {
        httpRouter.use(await createRouter({ httpAuth, todoList }));

        // Backends are secure-by-default. Open specific endpoints explicitly:
        httpRouter.addAuthPolicy({ path: '/health', allow: 'unauthenticated' });
      },
    });
  },
});

Add more core services to deps as you need them (e.g. logger, database, userInfo, auth, scheduler).

3) src/index.ts — default export

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

Keep this line only in index.ts. Don't duplicate it inside plugin.ts.

4) src/router.ts — minimal Express router

Use express-promise-router so thrown errors propagate to the root error handler. Validate request bodies with zod. Check user credentials inline with httpAuth.credentials:

import type { HttpAuthService } from '@backstage/backend-plugin-api';
import { InputError } from '@backstage/errors';
import express from 'express';
import Router from 'express-promise-router';
import { z } from 'zod/v3';
import type { todoListServiceRef } from './services/TodoListService';

export async function createRouter({
  httpAuth,
  todoList,
}: {
  httpAuth: HttpAuthService;
  todoList: typeof todoListServiceRef.T;
}): Promise<express.Router> {
  const router = Router();
  router.use(express.json());

  const todoSchema = z.object({
    title: z.string(),
    entityRef: z.string().optional(),
  });

  router.post('/todos', async (req, res) => {
    const parsed = todoSchema.safeParse(req.body);
    if (!parsed.success) {
      throw new InputError(parsed.error.toString());
    }
    const result = await todoList.createTodo(parsed.data, {
      credentials: await httpAuth.credentials(req, { allow: ['user'] }),
    });
    res.status(201).json(result);
  });

  router.get('/todos', async (_req, res) => {
    res.json(await todoList.listTodos());
  });

  router.get('/todos/:id', async (req, res) => {
    res.json(await todoList.getTodo({ id: req.params.id }));
  });

  return router;
}

5) 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/todos returns an empty list. addAuthPolicy allowed /health through unauthenticated; every other path requires a valid user or service credential.

6) Services, DB, auth, identity (when needed)

• Service refs: define with createServiceRef<T>({ id: 'example.todoList' }), register with createServiceFactory({ service, deps, factory }). Pattern in the scaffold: services/TodoListService.ts exports the ref plus todoListServiceFactory which is registered via the plugin's register(env).
• Database: depend on coreServices.database to get a Knex client; run your own migrations with knex.migrate.latest(...) in init.
• Identity: use coreServices.httpAuth + coreServices.userInfo to obtain the calling user and their entity refs.
• Inter-plugin calls: use coreServices.auth to mint a token on behalf of the current caller, then coreServices.discovery for the target plugin's base URL — see Core Services reference.
• Full catalog of core services: see ⚙️ Core Services Reference.

---

Modules and extension points

Modules are packages that extend an existing plugin at a pre-defined integration point. Use them to add processors, providers, actions, etc., without forking the plugin.

Exposing an extension point (in a plugin):

import {
  createBackendPlugin,
  createExtensionPoint,
} from '@backstage/backend-plugin-api';

interface ExampleProcessor {
  process(value: string): Promise<string>;
}

export interface ExampleProcessingExtensionPoint {
  addProcessor(p: ExampleProcessor): void;
}

export const exampleProcessingExtensionPoint =
  createExtensionPoint<ExampleProcessingExtensionPoint>({
    id: 'example.processing',
  });

export const examplePlugin = createBackendPlugin({
  pluginId: 'example',
  register(env) {
    const processors: ExampleProcessor[] = [];

    env.registerExtensionPoint(exampleProcessingExtensionPoint, {
      addProcessor(p) {
        processors.push(p);
      },
    });

    env.registerInit({
      deps: { /* ... */ },
      async init() {
        // Use `processors` during plugin setup.
      },
    });
  },
});

Extending a plugin (in a module):

import { createBackendModule } from '@backstage/backend-plugin-api';
import { exampleProcessingExtensionPoint } from '@example/plugin-example-node';

export const exampleModuleCustomProcessor = createBackendModule({
  pluginId: 'example',
  moduleId: 'custom-processor',
  register(env) {
    env.registerInit({
      deps: { example: exampleProcessingExtensionPoint },
      async init({ example }) {
        example.addProcessor(new MyCustomProcessor());
      },
    });
  },
});

// src/index.ts
export { exampleModuleCustomProcessor as default } from './module';

Scaffold a module with yarn new → backend-module. Generated packages live in plugins/<pluginId>-backend-module-<moduleId>/.

---

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 (yarn start). Then check:
  • GET http://localhost:7007/api/example/health → { "status": "ok" } (if your plugin exposes a /health endpoint and opens it with addAuthPolicy).
  • If you get a 401, the request hit an authenticated endpoint without a valid token — either authenticate, or open the path with addAuthPolicy.

Testing, linting & structure checks

# Always pass --watchAll=false when running non-interactively (CI, AI agents);
# without it jest starts in watch mode and never exits.
yarn backstage-cli package test --watchAll=false
yarn backstage-cli package lint
yarn backstage-cli repo lint

Keep routers small (/router.ts), inject dependencies (DB, auth, clients) from plugin.ts, and avoid in-memory state so the backend stays horizontally scalable.

---

Common Pitfalls (and Fixes)

Problem	Solution
404s under /api	Backstage prefixes plugin routers with /api/<pluginId>. Don't add the prefix yourself in your route definitions.
Auth unexpectedly required	Backends are secure by default; open endpoints explicitly via httpRouter.addAuthPolicy({ path, allow: 'unauthenticated' }).
Tight coupling between plugins	Never import other backend plugins' internals. Communicate over HTTP using discovery + auth (auth.getPluginRequestToken({ onBehalfOf, targetPluginId })), or use extension points/modules.
errorHandler not found	@backstage/backend-common has been removed. Use MiddlewareFactory.create({ config, logger }).error() from @backstage/backend-defaults/rootHttpRouter, or rely on the root error handler that's installed automatically.
Tests hang or timeout	Make sure startTestBackend is awaited, and use await request(server).get(...) (from supertest), not server.request(...).
MSW handlers stop matching	MSW v2 uses http.get(url, () => HttpResponse.json(...)), not rest.get. Update imports and handler signatures.
Migrations don't run in prod	Migrations must be .js files listed in your package.json files array, so they're copied into the published artifact.

---

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 / Root HTTP Router for route registration
  • Logger / Root Logger for structured logging
  • Database Service for Knex-based data access
  • HTTP Auth + User Info + Auth services
  • Cache, Scheduler, URL Reader, Discovery services
  • Permissions + Permissions Registry for authorization
  • Auditor, Lifecycle, Root Config, Root Health, Plugin Metadata
  • Service composition examples and best practices

Testing

• ✅ Testing Reference - Comprehensive testing guide including:
  • Testing backend plugins with startTestBackend
  • The mockServices catalog and mockCredentials helpers
  • Testing routers with supertest (using await request(server).get(...))
  • Testing authentication, permissions, and scheduled tasks
  • External service mocking with MSW v2
  • Database testing with TestDatabases (from @backstage/backend-test-utils)
  • Service factory testing, module testing, and integration patterns

---

External References

• Backend Plugins and Modules — authoring plugins and modules.
• Core Backend Services — index of all core services.
• Testing Backend Plugins — official testing guide.
• Migrating Backends — legacy-to-new-system migration (covers errorHandler → MiddlewareFactory).