Backstage TODO Plugin

TODO is the comment you leave when you cannot fix something right now. Over time those notes pile up across repos and languages. They hide in code. The TODO plugin brings them into Backstage so you can see them in one place.

It lists TODO and FIXME items for each catalog entity. A small backend service scans source locations and feeds a table on the entity page. You get the text, tag, author, file path, and a link back to the line in source. You can sort or filter by tag or author to focus on what matters.

The default parser understands many languages and common formats. Teams can extend tags to match their style. Dot files are ignored to reduce noise. Inline trailing comments are skipped to avoid false hits.

Use it to surface technical debt before a release. Triage findings during cleanup days. Track hotspots in a service to guide refactors. Review TODOs during ownership handoffs. Add custom tags like NOTE or XXX to flag risk or urgency. The plugin fits naturally in Backstage with minimal ceremony, so you get quick value without changing your issue tracker or workflow.

If you run a self hosted Backstage, this adds immediate visibility into real work left in code. It turns scattered TODOs into clear, searchable tasks inside your portal.

Installation Instructions

These instructions apply to self-hosted Backstage only.

Install the frontend plugin

Run this in the root of your Backstage repo

Copy

yarn --cwd packages/app add @backstage-community/plugin-todo

Add the Todo tab on entity pages

Edit packages app src components catalog EntityPage tsx

Copy

// packages/app/src/components/catalog/EntityPage.tsx
import React from 'react';
import { EntityLayout } from '@backstage/plugin-catalog';
import { EntityTodoContent } from '@backstage-community/plugin-todo';

const serviceEntityPage = (
  <EntityLayout>
    {/* other tabs */}
    <EntityLayout.Route path="/todo" title="Todo">
      <EntityTodoContent />
    </EntityLayout.Route>
  </EntityLayout>
);

export default serviceEntityPage;

Use the new frontend system

If your app uses the new frontend system, register the feature in App tsx

Copy

// packages/app/src/App.tsx
import { createApp } from '@backstage/app-defaults';
import todoPlugin from '@backstage-community/plugin-todo/alpha';

export const app = createApp({
  features: [
    todoPlugin,
  ],
});

export default app;

Install the backend plugin

The frontend needs the Todo backend. Install it in your backend package

Copy

yarn --cwd packages/backend add @backstage-community/plugin-todo-backend

Legacy backend setup

Create a router for the plugin

Copy

// packages/backend/src/plugins/todo.ts
import { Router } from 'express';
import { createRouter } from '@backstage-community/plugin-todo-backend';
import { PluginEnvironment } from '../types';

export default async function createPlugin(
  env: PluginEnvironment,
): Promise<Router> {
  return await createRouter({
    logger: env.logger,
    config: env.config,
    reader: env.reader,
    discovery: env.discovery,
    tokenManager: env.tokenManager,
    permissions: env.permissions,
  });
}

Mount the router in your backend

Copy

// packages/backend/src/index.ts
import todo from './plugins/todo';

// inside your main bootstrap function
const todoEnv = useHotMemoize(module, () => createEnv('todo'));
apiRouter.use('/todo', await todo(todoEnv));

The mount path above becomes the service base path. The frontend discovers it through service discovery.

New backend system setup

Add the module to your backend builder

Copy

// packages/backend/src/index.ts
import { createBackend } from '@backstage/backend-defaults';
import { todoPlugin } from '@backstage-community/plugin-todo-backend';

const backend = createBackend();

backend.add(todoPlugin());

backend.start();

Keep your existing builder import if it differs. Only the add line matters for this plugin.

Notes on formats

The backend scans source code for TODO and FIXME by default using Leasot. You can keep defaults to start. If you need custom tags or parsing rules, configure that in the Todo backend package config later.

Changelog

This changelog is produced from commits made to the TODO plugin since a year ago. It may not contain information about all commits. Releases and version bumps are intentionally omitted. This changelog is generated by AI.

Features

Add support for the new frontend system in the Todo frontend #4825 2 months ago

Documentation

Fix the Todo frontend README. Link to the backend README #3907 4 months ago

Maintenance

Remove usages of the backend common package in the Todo backend #2583 6 months ago
Reduce knip false positives in the repo setup #3018 6 months ago

Dependencies

Remove unused dev dependency canvas #3565 5 months ago

Deprecations

Deprecate the legacy Todo backend #2053 10 months ago
Use the new backend system

Set up Backstage in minutes with Roadie

Focus on using Backstage, rather than building and maintaining it.

Get a demo