or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

api-implementations.mdapi-system.mdapp-creation.mdauthentication.mdindex.mdrouting.md
tile.json

tessl/npm-backstage--core-app-api

Core API library that provides essential application programming interfaces for Backstage apps, including routing functionality, app configuration management, and core services that enable frontend applications to interact with the Backstage ecosystem.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@backstage/core-app-api@1.10.x

To install, run

npx @tessl/cli install tessl/npm-backstage--core-app-api@1.10.0

index.mddocs/

@backstage/core-app-api

@backstage/core-app-api is the foundational API library for Backstage applications, providing essential application programming interfaces including routing functionality, app configuration management, and core services that enable frontend applications to interact with the Backstage ecosystem. It serves as the foundational layer for building Backstage frontend applications and plugins.

Package Information

  • Package Name: @backstage/core-app-api
  • Package Type: npm
  • Language: TypeScript
  • Installation: yarn add @backstage/core-app-api

Core Imports

import { createSpecializedApp, AppRouter, FlatRoutes } from "@backstage/core-app-api";

For specific APIs:

import { 
  ApiProvider, 
  ConfigReader, 
  LocalStorageFeatureFlags,
  GithubAuth,
  FetchApi 
} from "@backstage/core-app-api";
import { ComponentType } from "react";

Basic Usage

import { createSpecializedApp, AppRouter } from "@backstage/core-app-api";
import { FlatRoutes } from "@backstage/core-app-api";

// Create a Backstage app
const app = createSpecializedApp({
  apis: [
    // API factory configurations
  ],
  components: {
    NotFoundErrorPage: MyNotFoundPage,
    BootErrorPage: MyBootErrorPage,
    Progress: MyProgressComponent,
    Router: MyRouter,
    ErrorBoundaryFallback: MyErrorBoundary,
  },
  themes: [
    {
      id: 'light',
      title: 'Light Theme',
      variant: 'light',
      Provider: MyLightThemeProvider,
    }
  ],
  icons: {
    'kind:api': ApiIcon,
    'kind:component': ComponentIcon,
    // ... other required icons
  },
  plugins: [],
});

// Create the root app component
export default app.createRoot(
  <>
    <AppRouter>
      <FlatRoutes>
        {/* Your routes here */}
      </FlatRoutes>
    </AppRouter>
  </>
);

Architecture

@backstage/core-app-api is organized into four main areas:

  • API System: Core API management infrastructure with dependency injection and factory pattern
  • API Implementations: Concrete implementations for all major Backstage APIs including authentication providers
  • App Creation: Application initialization, configuration, and lifecycle management
  • Routing: Route management components with feature flagging and plugin integration

The library follows a factory pattern with dependency injection, enabling flexible API registration and resolution. Authentication providers support all major OAuth providers plus SAML. The system provides type safety throughout with comprehensive TypeScript interfaces.

Capabilities

API System

Core API management infrastructure providing dependency injection and factory registration for all Backstage APIs.

export class ApiProvider extends React.Component<ApiProviderProps>;

export interface ApiProviderProps {
  apis: ApiHolder;
  children: React.ReactNode;
}

export class ApiResolver {
  constructor(factories: ApiFactoryHolder);
  get<T>(api: ApiRef<T>): T;
}

export class ApiFactoryRegistry {
  register<T>(
    scope: ApiFactoryScope,
    factory: AnyApiFactory
  ): boolean;
  get<T>(api: ApiRef<T>): ApiFactory<T> | undefined;
}

export type ApiFactoryScope = 'default' | 'app' | 'static';

API System

API Implementations

Comprehensive set of concrete API implementations for all core Backstage functionality including authentication, configuration, analytics, and more.

// Alert API
export class AlertApiForwarder implements AlertApi {
  constructor();
  post(message: AlertMessage): void;
}

// Analytics API
export class MultipleAnalyticsApi implements AnalyticsApi {
  constructor(apis: AnalyticsApi[]);
  captureEvent(event: AnalyticsEvent): void;
}

// Configuration API
export class ConfigReader implements Config {
  constructor(data?: ConfigValue, prefix?: string);
  get<T = JsonValue>(key?: string): T;
  getOptional<T = JsonValue>(key?: string): T | undefined;
  has(key: string): boolean;
  keys(): string[];
  getConfig(key: string): Config;
  getOptionalConfig(key: string): Config | undefined;
}

// Discovery API
export class UrlPatternDiscovery implements DiscoveryApi {
  constructor(pattern: string);
  getBaseUrl(pluginId: string): Promise<string>;
}

// Feature Flags API
export class LocalStorageFeatureFlags implements FeatureFlagsApi {
  constructor();
  isActive(name: string): boolean;
  registerFlag(flag: FeatureFlag): void;
  getRegisteredFlags(): FeatureFlag[];
}

API Implementations

Authentication Providers

Comprehensive authentication provider ecosystem supporting OAuth2, SAML, and all major identity providers.

// OAuth2 Generic Provider
export class OAuth2 implements AuthProvider {
  static create(options: OAuth2CreateOptions): AuthProvider;
  getAccessToken(scope?: string): Promise<string>;
}

// GitHub Authentication
export class GithubAuth {
  static create(options: OAuthApiCreateOptions): AuthProvider;
}

// Google Authentication  
export class GoogleAuth {
  static create(options: OAuthApiCreateOptions): AuthProvider;
}

// Microsoft Authentication
export class MicrosoftAuth {
  static create(options: OAuthApiCreateOptions): AuthProvider;
}

// Additional providers: GitlabAuth, OktaAuth, OneLoginAuth, 
// AtlassianAuth, BitbucketAuth, BitbucketServerAuth, SamlAuth

Authentication Providers

App Creation and Configuration

Application creation infrastructure for initializing Backstage apps with comprehensive configuration options.

export function createSpecializedApp(options: AppOptions): BackstageApp;

export interface AppOptions {
  apis?: Iterable<AnyApiFactory>;
  defaultApis?: Iterable<AnyApiFactory>;
  icons: AppIcons & { [key in string]: IconComponent };
  plugins?: Array<BackstagePlugin>;
  featureFlags?: FeatureFlag[];
  components: AppComponents;
  themes: (Partial<AppTheme> & Omit<AppTheme, 'theme'>)[];
  configLoader?: AppConfigLoader;
  bindRoutes?(context: { bind: AppRouteBinder }): void;
}

export interface BackstageApp {
  getPlugins(): BackstagePlugin[];
  getSystemIcon(key: string): IconComponent | undefined;
  createRoot(element: JSX.Element): ComponentType<PropsWithChildren<{}>>;
}

export const AppRouter: React.ComponentType<AppRouterProps>;

export interface AppRouterProps {
  children?: React.ReactNode;
  basename?: string;
}

App Creation

Routing and Navigation

Route management components with feature flagging, plugin integration, and React Router compatibility.

export const FlatRoutes: React.ComponentType<FlatRoutesProps>;

export interface FlatRoutesProps {
  children?: React.ReactNode;
}

export const FeatureFlagged: React.ComponentType<FeatureFlaggedProps>;

export interface FeatureFlaggedProps {
  with: string;
  children?: React.ReactNode;
}

Routing

Type Definitions

Note: Some types reference interfaces from @backstage/core-plugin-api such as BackstagePlugin, IdentityApi, ExternalRouteRef, etc. These are imported from the companion package:

import { BackstagePlugin, IdentityApi, ExternalRouteRef } from "@backstage/core-plugin-api";

Core App Types

export interface AppComponents {
  NotFoundErrorPage: ComponentType<PropsWithChildren<{}>>;
  BootErrorPage: ComponentType<BootErrorPageProps>;
  Progress: ComponentType<PropsWithChildren<{}>>;
  Router: ComponentType<PropsWithChildren<{ basename?: string }>>;
  ErrorBoundaryFallback: ComponentType<ErrorBoundaryFallbackProps>;
  ThemeProvider?: ComponentType<PropsWithChildren<{}>>;
  SignInPage?: ComponentType<SignInPageProps>;
}

export interface AppIcons {
  'kind:api': IconComponent;
  'kind:component': IconComponent;
  'kind:domain': IconComponent;
  'kind:group': IconComponent;
  'kind:location': IconComponent;
  'kind:system': IconComponent;
  'kind:user': IconComponent;
  brokenImage: IconComponent;
  catalog: IconComponent;
  chat: IconComponent;
  dashboard: IconComponent;
  docs: IconComponent;
  email: IconComponent;
  github: IconComponent;
  group: IconComponent;
  help: IconComponent;
  scaffolder: IconComponent;
  search: IconComponent;
  techdocs: IconComponent;
  user: IconComponent;
  warning: IconComponent;
}

export interface BootErrorPageProps {
  step: 'load-config' | 'load-chunk';
  error: Error;
  children?: React.ReactNode;
}

export interface SignInPageProps {
  onSignInSuccess(identityApi: IdentityApi): void;
  children?: React.ReactNode;
}

export interface ErrorBoundaryFallbackProps {
  plugin?: BackstagePlugin;
  error: Error;
  resetError: () => void;
  children?: React.ReactNode;
}

export type IconComponent = ComponentType<
  | {
      fontSize?: 'large' | 'small' | 'default';
    }
  | {
      fontSize?: 'medium' | 'large' | 'small';
    }
>;

export type AppConfigLoader = () => Promise<AppConfig[]>;

export type AppRouteBinder = <
  ExternalRoutes extends { [name: string]: ExternalRouteRef },
>(
  externalRoutes: ExternalRoutes,
  targetRoutes: PartialKeys<
    TargetRouteMap<ExternalRoutes>,
    KeysWithType<ExternalRoutes, ExternalRouteRef<any, true>>
  >,
) => void;

export interface AppContext {
  getPlugins(): BackstagePlugin[];
  getSystemIcon(key: string): IconComponent | undefined;
  getSystemIcons(): Record<string, IconComponent>;
  getComponents(): AppComponents;
}

Authentication Types

export interface OAuth2CreateOptions {
  discoveryApi: DiscoveryApi;
  oauthRequestApi: OAuthRequestApi;
  provider: AuthProvider;
  defaultScopes?: string[];
  additionalScopes?: Record<string, string[]>;
}

export interface OAuthApiCreateOptions {
  discoveryApi: DiscoveryApi;
  oauthRequestApi: OAuthRequestApi;
  provider: AuthProvider;
}

export interface AuthApiCreateOptions {
  discoveryApi: DiscoveryApi;
  oauthRequestApi: OAuthRequestApi;
  provider: AuthProvider;
}