New plugin: Extendable Guided Tours (using BUI and NFS)

.github/CODEOWNERS

@@ -74,6 +74,7 @@ yarn.lock                                                               @backsta
 /workspaces/grafana                                                     @backstage/community-plugins-maintainers
 /workspaces/graphiql                                                    @backstage/community-plugins-maintainers
 /workspaces/graphql-voyager                                             @backstage/community-plugins-maintainers
+/workspaces/guided-tours                                                @backstage/community-plugins-maintainers  @christoph-jerolimov @ciiay @debsmita1 @divyanshiGupta @its-mitesh-kumar @logonoff @lokanandaprabhu @rohitkrai03 @karthikjeeyar
 /workspaces/healert                                                     @backstage/community-plugins-maintainers  @amgadmag  @israa-mosad
 /workspaces/ilert                                                       @backstage/community-plugins-maintainers
 /workspaces/jaeger                                                      @backstage/community-plugins-maintainers

workspaces/guided-tours/.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets)
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

workspaces/guided-tours/.changeset/config.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "privatePackages": {
+    "tag": false,
+    "version": false
+  }
+}

workspaces/guided-tours/.changeset/guided-tours-initial.md

@@ -0,0 +1,6 @@
+---
+'@backstage-community/plugin-guided-tours': minor
+'@backstage-community/plugin-guided-tours-react': minor
+---
+
+Added the guided tours plugins for the new frontend system: spotlight steps on top of any page, per-user progress and automatic start on login or on the first visit of a path. See the [README](https://github.com/backstage/community-plugins/tree/main/workspaces/guided-tours/plugins/guided-tours#readme) for all the details.

workspaces/guided-tours/.dockerignore

@@ -0,0 +1,8 @@
+.git
+.yarn/cache
+.yarn/install-state.gz
+node_modules
+packages/*/src
+packages/*/node_modules
+plugins
+*.local.yaml

workspaces/guided-tours/.eslintignore

@@ -0,0 +1,2 @@
+e2e-tests
+playwright.config.ts

workspaces/guided-tours/.eslintrc.js

@@ -0,0 +1 @@
+module.exports = require('../../.eslintrc.cjs');

workspaces/guided-tours/.gitignore

@@ -0,0 +1,54 @@
+# macOS
+.DS_Store
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# Coverage directory generated when running tests with coverage
+coverage
+
+# Dependencies
+node_modules/
+
+# Yarn files
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+
+# Node version directives
+.nvmrc
+
+# dotenv environment variables file
+.env
+.env.test
+
+# Build output
+dist
+dist-types
+
+# Temporary change files created by Vim
+*.swp
+
+# MkDocs build output
+site
+
+# Local configuration files
+*.local.yaml
+
+# Sensitive credentials
+*-credentials.yaml
+
+# vscode database functionality support files
+*.session.sql
+
+# E2E test reports
+e2e-test-report/

workspaces/guided-tours/.prettierignore

@@ -0,0 +1,6 @@
+dist
+dist-types
+coverage
+.vscode
+.eslintrc.js
+knip-report.md

workspaces/guided-tours/README.md

@@ -0,0 +1,38 @@
+# Guided Tours plugin for Backstage
+
+This workspace contains the guided tours plugins for Backstage: spotlight
+steps on top of any page, per-user progress and automatic start on login or
+on the first visit of a path. They target the new frontend system.
+
+## Plugins
+
+- [plugin-guided-tours](./plugins/guided-tours/README.md): the tour runner,
+  the overlay and the overview page at `/guided-tours`.
+- [plugin-guided-tours-react](./plugins/guided-tours-react/README.md): the
+  blueprint, API ref and hooks that let any frontend plugin ship a tour.
+
+## Getting Started
+
+To start the dev app, run:
+
+```sh
+yarn install
+yarn start
+```
+
+It opens a portal-like demo at http://localhost:3000 with a welcome tour and
+page tours for the catalog, templates, notifications and settings.
+
+## Tests
+
+```sh
+yarn test            # unit tests
+yarn test:e2e        # Playwright tests against the dev app
+```
+
+To generate the API and knip reports for this workspace, run:
+
+```sh
+yarn build:api-reports
+yarn build:knip-reports
+```

workspaces/guided-tours/backstage.json

@@ -0,0 +1,3 @@
+{
+  "version": "1.56.2"
+}

workspaces/guided-tours/bcp.json

@@ -0,0 +1,7 @@
+{
+  "autoVersionBump": true,
+  "knipReports": true,
+  "listDeprecations": true,
+  "playwrightTests": true,
+  "codecov": true
+}

workspaces/guided-tours/e2e-tests/guided-tours-page.test.ts

@@ -0,0 +1,92 @@
+/*
+ * Copyright 2026 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { expect, test } from '@playwright/test';
+import { closeTour, resetAllTours, step, stepButton } from './helpers';
+
+test.describe('guided tours page', () => {
+  test.beforeEach(async ({ page }) => {
+    await resetAllTours(page);
+    await page.goto('/guided-tours');
+    await closeTour(page);
+  });
+
+  test('lists every tour with its status and lets the user start, continue and restart', async ({
+    page,
+  }) => {
+    await expect(
+      page.getByRole('heading', { name: 'Guided tours' }).first(),
+    ).toBeVisible();
+    for (const title of [
+      'Welcome to Backstage',
+      'The software catalog',
+      'Create from a template',
+      'Your notifications',
+      'Your settings',
+    ]) {
+      await expect(page.getByRole('heading', { name: title })).toBeVisible();
+    }
+    const welcome = page.locator(
+      '[data-guided-tour="guided-tours.row.guided-tours/welcome"]',
+    );
+    const catalog = page.locator(
+      '[data-guided-tour="guided-tours.row.guided-tours/catalog"]',
+    );
+    await expect(welcome.getByText('Dismissed')).toBeVisible();
+    await expect(catalog.getByText('New')).toBeVisible();
+    await expect(
+      catalog.getByText('3 steps · Starts on first visit of /catalog'),
+    ).toBeVisible();
+
+    // Start opens the tour on the page of its first step
+    await catalog.getByRole('button', { name: 'Start' }).click();
+    await expect(page).toHaveURL(/\/catalog/);
+    await expect(step(page, 'Pick a kind')).toBeVisible();
+    await stepButton(page, 'Next').click();
+    await expect(step(page, 'Yours, starred, or everything')).toBeVisible();
+
+    // a tour left on another page is not resumed here, the page offers to
+    // continue it where it was
+    await page.goto('/guided-tours');
+    await expect(catalog.getByText('In progress')).toBeVisible();
+    await expect(page.getByRole('dialog')).toHaveCount(0);
+    await catalog.getByRole('button', { name: 'Continue' }).click();
+    await expect(page).toHaveURL(/\/catalog/);
+    await expect(
+      step(page, 'Yours, starred, or everything').getByText('Step 2 of 3'),
+    ).toBeVisible();
+    await closeTour(page);
+
+    // dismissed and completed tours can be restarted from the first step
+    await page.goto('/guided-tours');
+    await expect(catalog.getByText('Dismissed')).toBeVisible();
+    await welcome.getByRole('button', { name: 'Restart' }).click();
+    await expect(
+      step(page, 'Welcome 👋').getByText('Step 1 of 6'),
+    ).toBeVisible();
+    await closeTour(page);
+
+    // Reset all asks for confirmation and clears every status
+    await page.getByRole('button', { name: 'Reset all tours' }).click();
+    await expect(
+      page.getByRole('dialog').getByText('Reset all tours?'),
+    ).toBeVisible();
+    await page.getByRole('button', { name: 'Cancel' }).click();
+    await expect(welcome.getByText('Dismissed')).toBeVisible();
+    await page.getByRole('button', { name: 'Reset all tours' }).click();
+    await page.getByRole('button', { name: 'Reset', exact: true }).click();
+    await expect(page.getByText('New')).toHaveCount(5);
+  });
+});

workspaces/guided-tours/e2e-tests/helpers.ts

@@ -0,0 +1,52 @@
+/*
+ * Copyright 2026 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { expect, Page } from '@playwright/test';
+
+/** The button inside the step card; the dev pages have other Next/Previous buttons. */
+export const stepButton = (page: Page, name: 'Previous' | 'Next' | 'Done') =>
+  page.getByRole('dialog').getByRole('button', { name, exact: true });
+
+/** The step card: a centered dialog named after its heading, or an anchored popover. */
+export const step = (page: Page, title: string) =>
+  page.getByRole('dialog', { name: title });
+
+export const spotlight = (page: Page) =>
+  page.getByTestId('guided-tour-spotlight');
+
+/** Closes a running tour, if any. Tours start a moment after the page loads. */
+export async function closeTour(page: Page) {
+  const close = page.getByRole('button', { name: 'Close tour' });
+  await close
+    .first()
+    .waitFor({ state: 'visible', timeout: 3000 })
+    .catch(() => undefined);
+  if (await close.count()) {
+    await close.first().click();
+  }
+  await expect(page.getByRole('dialog')).toHaveCount(0);
+}
+
+/**
+ * Clears all progress through the guided tours page. The welcome tour then
+ * starts again on the next page load, as it does for a new user.
+ */
+export async function resetAllTours(page: Page) {
+  await page.goto('/guided-tours');
+  await closeTour(page);
+  await page.getByRole('button', { name: 'Reset all tours' }).click();
+  await page.getByRole('button', { name: 'Reset', exact: true }).click();
+  await expect(page.getByRole('dialog')).toHaveCount(0);
+}