Backstage
    Preparing search index...

    The app's shared navigation and location interface, used by plugins and app chrome. The default implementation owns browser history; apps can provide a custom implementation through an API factory.

    The public navigation surface mirrors the navigate + useHref pattern used by libraries like react-aria: AppHistoryApi.navigate performs navigation, and AppHistoryApi.createHref (paired with the public useAppHref hook) resolves an app-absolute path (starting at /, without the deployment basename) to a browser-ready href.

    interface AppHistoryApi {
        navigate: AppNavigate;
        createHref(to: string): string;
        getSnapshot(): AppHistorySnapshot;
        subscribe(listener: () => void): () => void;
    }
    Index
    navigate: AppNavigate

    Navigate to an app-absolute path or an external URL.

    Path targets must start with / and exclude the deployment basename. Empty, query-only, and hash-only targets use the current pathname. An empty target clears query and hash. Path-relative targets, including . and .., are rejected; use a page routing adapter for library-relative navigation.

    Absolute URLs (including same-origin URLs), protocol-relative URLs, and schemes such as mailto: are handled by the browser. The replace option replaces the browser history entry; state is only used for app-absolute path navigation. Executable URL schemes are replaced with about:blank and a warning.

    Successful app-absolute pushes and replacements update getSnapshot() and notify subscribers synchronously before returning. Numeric history traversal may complete asynchronously and is observed through subscribe. External navigation does not synchronously update the app location.

    • Resolve a path to a browser-ready href, including the app's deploy basename.

      Executable URL schemes are replaced with about:blank and a warning.

      Paths must start with / and exclude the deployment basename. Relative paths are rejected. Empty, query-only, and hash-only targets, such as ?tab=readme or #section, use the current pathname.

      Absolute URLs, protocol-relative URLs, and schemes such as mailto: and tel: pass through without the basename, after sanitization.

      Only the path portion is inspected, so /search?query=https://example.com is an ordinary app-absolute target.

      Parameters

      • to: string

      Returns string

    • Reads the current immutable history snapshot without writing history.

      Returns the same object until navigation is published. Reads do not discover browser history writes that have not been reported to subscribers, including silent URL synchronization by plugins.

      Each committed navigation publishes a new snapshot, even when its URL and state are unchanged. The nested location retains its identity while its fields are unchanged.

      This function has a stable identity and can be called without binding it to the API instance, including as useSyncExternalStore's getSnapshot.

      Returns AppHistorySnapshot

    • Subscribes to history changes. The snapshot is updated before listeners are called. Successful internal pushes and replacements notify synchronously before navigate returns; traversals may finish asynchronously.

      Subscribing does not invoke the listener immediately. Read getSnapshot for the current value. Returns an idempotent unsubscribe function.

      This function has a stable identity and can be called without binding it to the API instance, including as useSyncExternalStore's subscribe.

      Parameters

      • listener: () => void

      Returns () => void