8. Integrated Search

Backstage ships with a built-in search system that provides a unified search experience across all content in your developer portal. Instead of navigating through multiple sections to find something, developers can search catalog entities, documentation, and any other indexed content from a single place.

This chapter covers how search works, what gets indexed by default, and how to configure the search backend for production use.

How Backstage Search Works

The search system consists of three main building blocks:

At startup, the backend scheduler runs all registered collators, which feed their documents into the search engine. The frontend queries the search API and renders results using registered result extensions.

Task 8.1: Explore the Search UI

Let’s start by using the search feature that is already part of your Backstage app.

1. Open your Backstage instance at http://localhost:3000
2. Click the 🔍 icon in the left sidebar to open the search page, or navigate directly to http://localhost:3000/search
3. Try a few searches:
   • Type example to find the default catalog entities
   • Type platform to find Platform Engineers (users)
   • Type template to find the example scaffolder template

The search results show the entity name, kind, and a short description. Clicking a result navigates directly to that entity or document.

Task 8.2: Understand the Default Collators

Out of the box, Backstage indexes the following content:

Both collators are registered automatically when you create a new Backstage app.

To verify, open packages/backend/src/index.ts and look for the search module imports:

backend.add(import('@backstage/plugin-search-backend'));
backend.add(import('@backstage/plugin-search-backend-module-catalog'));
backend.add(import('@backstage/plugin-search-backend-module-techdocs'));

The search engine processes catalog and TechDocs content automatically on each refresh cycle (default: every 10 minutes).

Task 8.3: Configure the Search Schedule

The collator refresh interval can be configured in app-config.yaml. Add the following to adjust the schedule:

search:
  collators:
    catalog:
      schedule:
        frequency:
          minutes: 10
        timeout:
          minutes: 15
    techdocs:
      schedule:
        frequency:
          minutes: 30
        timeout:
          minutes: 15

More configuration options can be found here: https://backstage.io/docs/features/search/collators/#catalog

Search Result Types

Each collator registers its own result type. The frontend renders results differently depending on the type:

You can inspect the raw result documents at the search API endpoint:

GET http://localhost:7007/api/search/query?term=example

Summary

In this chapter, you:

• Explored the built-in Backstage search UI
• Learned about collators and how catalog and TechDocs content is indexed
• Configured the collator refresh schedule
• Understood how to replace the default Lunr engine with Elasticsearch for production

Backstage Search grows with your portal. As you add more plugins and data sources, you can register additional collators to make all content searchable from one place.

Next Steps

Now that you’ve completed this lab, you could:

1. Write a custom collator: Index content from an internal wiki, Confluence, or any other data source by implementing the DocumentCollatorFactory interface. See the official docs for details.
2. Customize result rendering: Register a custom SearchResultListItemExtension to control how your search results are displayed.
3. Add filters: Use SearchFilter components to let users narrow results by entity kind, namespace, or any other metadata field.