[christoph-jerolimov]

Hey, I just made a Pull Request!

Fixes #279.

Adds a new guided-tours workspace with two plugins for the new frontend system:

• @backstage-community/plugin-guided-tours: the tour runner, a spotlight overlay with step cards, per-user progress stored in the storage API, automatic start on login or on the first visit of a path, and an overview page at /guided-tours.
• @backstage-community/plugin-guided-tours-react: the GuidedTourBlueprint, API ref, hooks and target helpers that let any frontend plugin ship a tour without depending on the main plugin.

The main plugin comes with a dev app that showcases tours on the catalog, scaffolder, notifications and user settings pages.

Localization of the tour contents will follow in a later PR. The API for that is not settled yet.

Example

Any plugin ships a tour as an extension built with the GuidedTourBlueprint. Adopters can do the same in their app with a frontend module. When the guided-tours plugin is not installed, the extension stays unattached and nothing breaks.

import { createFrontendModule } from '@backstage/frontend-plugin-api';
import { GuidedTourBlueprint } from '@backstage-community/plugin-guided-tours-react';

const catalogIntroTour = GuidedTourBlueprint.make({
  name: 'intro',
  params: {
    title: 'The software catalog',
    description: 'A one minute walk through the catalog page.',
    // first visit of /catalog; add `exact: false` to start on entity pages too
    autoStart: { path: '/catalog' },
    steps: [
      {
        id: 'welcome',
        title: 'Welcome',
        content: 'The catalog lists **everything** your organization owns.',
      },
      {
        id: 'create',
        target: { selector: 'a[href="/create"]' },
        placement: 'bottom',
        content: 'Scaffold a new project from a template.',
      },
      {
        id: 'first-entity',
        target: { selector: 'table tbody tr' },
        advanceOn: 'click',
        content: 'Click an entity to open its page and finish the tour.',
      },
    ],
  },
});

// in packages/app, or in the `extensions` of your own plugin
export const catalogToursModule = createFrontendModule({
  pluginId: 'catalog',
  extensions: [catalogIntroTour],
});

The tour gets the id catalog/intro. Elements of your own UI are marked with guidedTourTargetProps('my-plugin.element') and referenced by that id as the step target.

Screenshots

	Light	Dark
Welcome step, centered
Anchored step with spotlight
Catalog tour, last step
Guided tours overview page

✔️ Checklist

• A changeset describing the change and affected packages. (more info)
• Added or updated documentation
• Tests for new functionality and regression tests for bug fixes
• Screenshots attached (for UI changes)
• All your commits have a Signed-off-by line in the message. (more info)

🤖 Generated with Claude Code

[backstage-goalie]

Important

This PR includes changes that affect public-facing API. Please ensure you are adding/updating documentation for new features or behavior.

Changed Packages

Package Name	Package Path	Changeset Bump	Current Version
@backstage-community/plugin-guided-tours-react	workspaces/guided-tours/plugins/guided-tours-react	minor	v0.0.0
@backstage-community/plugin-guided-tours	workspaces/guided-tours/plugins/guided-tours	minor	v0.0.0

[codecov]

Codecov Report

❌ Patch coverage is 98.17073% with 12 lines in your changes missing coverage. Please review.
✅ Project coverage is 98.17%. Comparing base (e04b47f) to head (e8a46f3).
⚠️ Report is 23 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff             @@
##             main   #11697       +/-   ##
===========================================
+ Coverage   75.50%   98.17%   +22.66%     
===========================================
  Files         630       24      -606     
  Lines       17182      656    -16526     
  Branches     4045      162     -3883     
===========================================
- Hits        12973      644    -12329     
+ Misses       4162       12     -4150     
+ Partials       47        0       -47     

Flag	Coverage Δ
acr	?
guided-tours	98.17% <98.17%> (?)
keycloak	?
nexus-repository-manager	?
ocm	?
pingidentity	?
quay	?
rbac	?
scaffolder-backend-module-annotator	?
scaffolder-backend-module-kubernetes	?
scaffolder-backend-module-regex	?
scaffolder-backend-module-servicenow	?
scaffolder-relation-processor	?
servicenow	?
tekton	?
topology	?

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 547ba27...e8a46f3. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[christoph-jerolimov]

Use to: string or page: string or subpage: string???