BTST Route Docs: Check Page Paths, Parameters, and Mounts

When a plugin page opens at the wrong path, inspect the resolved route configuration before changing redirects. The page mount, API mount, route parameters, and sitemap output each describe a different part of the integration.

BTST Route Docs provides a reference for registered client plugin routes. It is useful while wiring several plugins into an existing React app, especially when the site pages and API use different prefixes. This guide describes @btst/stack@3.0.0.

Register Route Docs on the client stack#

Route Docs is a client-only plugin. It reads the stack's registered client definitions and resolved site configuration; it does not need a Route Docs backend plugin or an extra API service.

This factory includes Blog as an example route source:

import { QueryClient } from "@tanstack/react-query";
import { createClientStack } from "@btst/stack/client";
import { blogClientPlugin } from "@btst/stack/plugins/blog/client";
import { routeDocsClientPlugin } from "@btst/stack/plugins/route-docs/client";

export function createDocumentedStack(baseURL: string) {
  return createClientStack({
    api: { baseURL, basePath: "/api/data" },
    site: { baseURL, basePath: "/p" },
    queryClient: new QueryClient(),
    plugins: {
      blog: blogClientPlugin(),
      routeDocs: routeDocsClientPlugin(),
    },
  });
}

Call the factory at the appropriate lifetime for your framework: a request-specific instance for SSR, and a stable instance for the browser's provider. Do not recreate the stack and query client on every component render. Mount the stack through the framework integration and StackProvider described in installation. Blog's backend must exist for its data operations.

With these paths, the reference page is /p/route-docs. The API remains under /api/data. The programmatic plugin key is routeDocs; the package and route use route-docs.

Know what the reference covers#

The reference inspects registered BTST client plugins. It is not a filesystem scanner for every Next.js page, TanStack route, or React Router module in your application. If an application-owned route is absent, first ask whether it is part of the BTST client definitions at all.

Route Docs displays route patterns and parameter information, supports constructing a Visit URL, and collects plugin sitemap entries. Use those surfaces together:

Open the generated Visit URL directly in a fresh tab as well as through client navigation. That catches a server catch-all route that is missing even though an already loaded browser can navigate internally.

Keep each stack's reference scoped#

The released useRegisteredRoutes() hook uses the stack provided by StackProvider; it can also accept a resolved stack explicitly outside the provider. This matters when an application has more than one stack. Inspect the reference under the same stack that renders the affected page.

A per-plugin site override belongs in createClientStack({ endpoints }). Verify both the displayed route and its actual Visit link after changing it. Changing a configuration string does not provision a route, proxy, or deployment at the new destination.

For request-time rendering, pass server request headers only through the documented server configuration. Do not put session cookies or authorization headers into a browser-visible endpoint override to make a broken request succeed.

Treat documentation and access as separate checks#

The reference reveals route structure, including administrative routes registered in the stack. For an internal debugging tool, register it only in development or protect its route with application authorization. Its presence does not grant permission to visit the documented resources, and hiding it does not protect their APIs.

Route Docs and OpenAPI also answer different questions. Route Docs describes plugin page navigation. OpenAPI describes documented backend operations and their input/output contract. Neither replaces runtime authorization. See BTST OpenAPI access and protected operations when the failing request is an API call.

Once the route works, verify meaningful HTML, canonical URLs, and actual sitemap output separately. A route reference is a debugging aid, not evidence that a page is crawlable or indexed. The Route Docs documentation has the complete configuration, and the plugin page shows its role alongside the other BTST tools.