Anatomía de Backstage: dos mitades y un plugin

Objetivos del capítulo

  • Distinguir frontend (React) y backend (Node) y su rol en el conjunto.

  • Nombrar los componentes del New Backend System y su flujo de arranque.

  • Explicar el modelo de plugins de tres tipos.

  • Describir CLI @backstage/cli y su rol en el desarrollo.

Las dos mitades: el portal y la cocina

Una IDP es un restaurante. Backstage es un restaurante con dos pisos: la sala (el portal que ven los developers) y la cocina (el backend que corre la lógica). Subir entre pisos se hace por una escalera que se llama plugin.

Cuando abres un Backstage en tu navegador, lo que ves es el frontend: una SPA React con Material UI, que compone páginas a partir de rutas. Detrás, un backend en Node + Express expone una API HTTP con la lógica del catalog, el scaffolder, los plugins de notificaciones, etc. La cocina y la sala se hablan por HTTP y por eventos; la sala nunca toca el catálogo directamente, le pide a la cocina.

Diagram
Figure 3. Arquitectura de Backstage (vista C4 nivel contenedor)
Backstage NO es monolítico

El frontend y el backend son proyectos separados que comparten un mismo monorepo. Pueden desplegarse juntos o por separado. Esa decisión influye en cap-15 (despliegue).

Frontend: React + Material UI

El frontend es una SPA React 18. Usa Material UI v5 como sistema de diseño y react-router-dom para el routing. Lo que ves cuando arrancas un Backstage por primera vez es producto de un app.tsx que importa plugins y los monta en rutas.

Tres piezas conviven en el frontend:

  • App.tsx — el shell. Define la página principal, la navegación lateral, el theme.

  • packages/app — donde vive el shell por defecto. Puedes customizarlo.

  • Plugins — cada plugin frontend expone extensions que se montan en el shell.

El :cap-08 entra a fondo en cómo escribir un plugin frontend.

Backend: Node, Express, Knex

El backend es una aplicación Node 20+ con Express y Knex. Maneja:

  • HTTP: rutas REST para el catalog, scaffolder, auth, etc.

  • DB: Knex con Postgres en producción, SQLite en dev.

  • Auth: verificación de tokens, mapeo de identity a user.

  • Servicios: el bus de dependencies injection que define la New Backend System.

El CLI @backstage/cli

Backstage trae un CLI propio: @backstage/cli. Es el ejecutor unificado de todas las tareas del monorepo: build, test, lint, dev, package start. Internamente, envuelve a tsc, webpack, jest, eslint, con la configuración por defecto que Backstage necesita.

Por qué un CLI propio

Cada plugin tiene la misma cadena de build/test/lint. Tener un CLI compartido la aplica consistentemente. El precio: se come algo de flexibilidad. Si necesitas algo personalizado, puedes escapar de él.

New Backend System vs legacy

Desde Backstage 1.20, la arquitectura recomendada es la New Backend System. Sustituye a la legacy backend system con una API limpia basada en createBackend(), BackendFeature y un bus de servicios llamado coreServices.

Diagram
Figure 4. Flujo de arranque de la New Backend System

La legacy backend system, basada en createPlugin() y routers montados en index.ts, sigue operativa por compatibilidad, pero el blog oficial la considera deprecated. Recomendamos migrar a la New Backend System: simplifica los servicios, mejora la inyección de dependencias y reduce el código boilerplate.

El :apéndice H entra en la migración.

El modelo de plugins: tres categorías

Backstage se extiende con plugins. Hay tres tipos:

Diagram
Figure 5. Tres tipos de plugins

  • Plugin frontend — un módulo React que expone rutas, componentes y APIs. Def: createPlugin() + createRoutableExtension().

  • Plugin backend — un módulo Node que define servicios, routers y eventos. Def: createBackendPlugin() o createBackendModule().

  • Scaffolder action — un paso ejecutable del Scaffolder. Def: createFrontendOrBackendAction().

Un plugin = un paquete

Cada plugin vive en su propio paquete del workspace. Esto aísla fallos: un plugin roto no rompe el resto. El :cap-06 y el :cap-08 construyen uno paso a paso.

Cómo se monta todo: flujo de arranque

El flujo de arranque de un Backstage es el siguiente:

  1. pnpm dev en el monorepo raíz.

  2. El frontend arranca en :code:`http://localhost:3000` (Vite, port 3000).

  3. El backend arranca en :code:`http://localhost:7007` (Node, Express).

  4. El frontend hace fetch al backend usando proxy: { '/api': 'http://localhost:7007' }.

  5. El backend resuelve sus coreServices (Database, Cache, Auth, Logger, HttpAuth).

  6. El backend aplica migraciones de DB.

  7. El backend levanta el socket y queda a la escucha.

A partir de ahí, el frontend y el backend se hablan por HTTP/JSON y por el sistema de eventos del backend.

Example 2. Receta del capítulo

  1. Identifica frontend (React) y backend (Node) como dos proyectos separados en el mismo monorepo.

  2. Usa el @backstage/cli para construir, testear y empaquetar.

  3. Prefiere la New Backend System (desde 1.20) sobre la legacy.

  4. Modela cada nuevo módulo como un plugin de uno de los tres tipos.

Resumen

  • Backstage = frontend React + backend Node + @backstage/cli, todo en un monorepo.

  • La New Backend System es la arquitectura por defecto desde la 1.20.

  • El modelo de plugins se divide en tres categorías: frontend, backend, scaffolder actions.

  • El CLI propio simplifica la cadena de build/test/lint de cada paquete.

Glosario del capítulo

SPA

Single Page Application. Aplicación web que carga una sola página y actualiza dinámicamente.

Knex

SQL query builder para Node. Usado por Backstage como capa de DB.

BackendFeature

Unidad de la New Backend System: un plugin, un módulo o un servicio.

coreServices

Bus de servicios del backend (Database, Cache, Auth, Logger, HttpAuth, etc.).

Plugin

Módulo de extensión. Hay tres tipos: frontend, backend, scaffolder action.

Próximo capítulo

Mise-en-place: tu primera IDP local —manos a la obra: bootstrap, levantar la cocina y cargar la primera entidad del catalog.