Backstage Template Builder

A Backstage plugin for visual template authoring

Visual authoring for Backstage scaffolder templates

What this is

Backstage scaffolder templates are powerful, but difficult to author, review, and evolve over time.

Backstage Template Builder is a Backstage frontend plugin that provides a visual editor, execution flow view, and live YAML output for creating and maintaining scaffolder templates — without hiding the underlying configuration.

This plugin is designed for platform teams who want faster, safer iteration on templates while staying fully compatible with Backstage's native scaffolder.

Key features

Visual template editor — Create and edit scaffolder templates using structured forms instead of hand-editing YAML
Live YAML view — Always see the generated YAML side-by-side to retain transparency and control
Template validation — Validate templates at any time with clickable issues that navigate directly to problems
RBAC support — Restrict access to platform engineers only using Backstage's permission system
Execution flow visualization — Understand how scaffolder steps execute through a clear, step-by-step flow view
Action discovery — Browse and add common scaffolder actions (fetch, publish, catalog, custom actions)
Preview experience — See what the end-user form will look like before publishing the template
GitHub integration — Load templates from GitHub repos with live search, push changes back with validation

Why this exists

Most Backstage adoption challenges don't come from running templates — they come from authoring and maintaining them.

This plugin focuses on:

Reducing YAML friction
Making template behavior understandable
Helping teams treat templates as long-lived products, not one-off files

Who it's for

Platform engineering teams
Backstage administrators
Architects and PMs defining golden paths
Anyone responsible for maintaining scaffolder templates at scale

Note: The plugin supports RBAC to ensure only authorized platform engineers can access it. See RBAC Configuration for setup instructions.

Quick Look

Create a new template

Load existing templates from GitHub

Deployment Options

Choose your platform:

⚡ For RHDH (Red Hat Developer Hub) - 2 Minute Setup

Use our pre-built dynamic plugin on Quay.io:

Plugin Image: quay.io/balajisivarh/backstage-template-builder:latest
Setup: Config-only, no code changes required
Access: /template-builder route with automatic menu integration

Quick Setup:

Add to your dynamic-plugins.yaml:

plugins:
  - package: oci://quay.io/balajisivarh/backstage-template-builder:latest!internal-plugin-backstage-template-builder
    disabled: false
    pluginConfig:
      dynamicPlugins:
        frontend:
          internal.backstage-plugin-template-builder:
            appIcons:
              - name: TemplateIcon
                importName: Description
            dynamicRoutes:
              - path: /template-builder
                importName: TemplateBuilderPage
                menuItem:
                  text: Template Builder
                  icon: TemplateIcon

Restart RHDH
Access at http://localhost:7007/template-builder

For detailed RHDH configuration, see RHDH Setup Guide below.

📦 For Standard Backstage - Full Integration

Install as a workspace plugin:

Installation: NPM or local workspace
Integration: Code changes in App.tsx
Guide: See BACKSTAGE-DEPLOYMENT.md

Not sure which? Check the Deployment Comparison Guide

Installation

Prerequisites

An existing Backstage instance (v1.x or higher)
Node.js 18+ and Yarn

Quick Start (Standard Backstage)

Copy the plugin to your Backstage monorepo:

cp -r plugins/backstage-template-builder <your-backstage-repo>/plugins/

Add the plugin to your app's dependencies:

In packages/app/package.json:

{
  "dependencies": {
    "@internal/plugin-backstage-template-builder": "^0.1.0"
  }
}

Install dependencies:
```
cd <your-backstage-repo>
yarn install
```

Add the route to your app:

In packages/app/src/App.tsx:

import { TemplateBuilderPage } from '@internal/plugin-backstage-template-builder';

// Inside <FlatRoutes>
<Route path="/template-builder" element={<TemplateBuilderPage />} />

Add to the sidebar (optional):

In packages/app/src/components/Root/Root.tsx:

import CodeIcon from '@material-ui/icons/Code';

// Inside the menu section
<SidebarItem icon={CodeIcon} to="/template-builder" text="Template Builder" />

Start Backstage:
```
yarn dev
```
Access the plugin:

Navigate to http://localhost:3000/template-builder (or click "Template Builder" in the sidebar)

Deployment Guides

Quick Reference:

QUAY-DEPLOYMENT.md - RHDH deployment (2-minute setup, config-only)
BACKSTAGE-DEPLOYMENT.md - Standard Backstage installation
DEPLOYMENT-COMPARISON.md - Platform comparison & decision guide
RHDH-DEPLOYMENT.md - Technical details for RHDH dynamic plugins

Additional Documentation:

Plugin README
Integration Guide
RBAC Configuration - Restrict access to platform engineers

RHDH (Red Hat Developer Hub) Setup

For RHDH deployments, use the pre-built dynamic plugin from Quay.io - no code changes required.

Quick Installation (Recommended)

Use the pre-built image from Quay.io:

Add plugin to dynamic-plugins.yaml:

plugins:
  - package: oci://quay.io/balajisivarh/backstage-template-builder:latest!internal-plugin-backstage-template-builder
    disabled: false
    pluginConfig:
      dynamicPlugins:
        frontend:
          internal.backstage-plugin-template-builder:
            appIcons:
              - name: TemplateIcon
                importName: Description
            dynamicRoutes:
              - path: /template-builder
                importName: TemplateBuilderPage
                menuItem:
                  text: Template Builder
                  icon: TemplateIcon

Restart RHDH:

podman compose down
podman compose up -d

Access the plugin:

Navigate to http://your-rhdh-host:7007/template-builder

The "Template Builder" menu item will appear automatically in the left sidebar.

Build from Source (For Customization)

If you want to customize the plugin or build from source:

Clone the repository:

git clone https://github.com/balajisiva/backstage-template-builder.git
cd backstage-template-builder/plugins/backstage-template-builder

Install dependencies:

yarn install

Export the dynamic plugin:

yarn export-dynamic

This creates dist-dynamic/ with the plugin bundle.

Option A: Use locally in RHDH

Copy the dist-dynamic folder to your RHDH instance:

cp -r dist-dynamic /path/to/rhdh/local-plugins/backstage-template-builder

Update dynamic-plugins.yaml:

plugins:
  - package: ./local-plugins/backstage-template-builder
    disabled: false
    pluginConfig:
      dynamicPlugins:
        frontend:
          internal.backstage-plugin-template-builder:
            appIcons:
              - name: TemplateIcon
                importName: Description
            dynamicRoutes:
              - path: /template-builder
                importName: TemplateBuilderPage
                menuItem:
                  text: Template Builder
                  icon: TemplateIcon

Option B: Build and push to your own registry

# Package as OCI image
npx @red-hat-developer-hub/cli@latest plugin package \
  --tag quay.io/YOUR_ORG/backstage-template-builder:v1.0.0

# Push to your registry
podman push quay.io/YOUR_ORG/backstage-template-builder:v1.0.0

Then reference your image in dynamic-plugins.yaml:

plugins:
  - package: oci://quay.io/YOUR_ORG/backstage-template-builder:v1.0.0!internal-plugin-backstage-template-builder
    disabled: false
    # ... rest of config

Configuration Options

Path: Change path: /template-builder to customize the URL route
Menu text: Change text: Template Builder to customize the sidebar label
Icon: Change icon: TemplateIcon to use a different Material-UI icon

Features in RHDH

All features work identically in RHDH:

Visual template editor
GitHub integration (with browser-stored PAT)
Live YAML preview
Template validation
Flow visualization
End-user preview

Permissions

By default, the plugin is accessible to all users. To restrict access, configure RBAC permissions in RHDH. The plugin exports the following permissions:

template.builder.use - Access the template builder
template.builder.create - Create new templates
template.builder.update - Modify existing templates

GitHub Integration

The plugin connects directly to GitHub to load and save templates. Users will need to provide a GitHub Personal Access Token:

Classic Token (recommended for simplicity):

Scope: repo (Full control of private repositories)
Create a classic token

Fine-grained Token (for more granular permissions):

Repository permissions:
- Contents: Read and Write
- Metadata: Read
Create a fine-grained token

Tokens are stored in the browser's localStorage and persist across sessions. They are never sent to any backend server - all GitHub API calls are made directly from the browser.

Usage

Once installed, users can:

Create new templates — Click "New" to start with a blank template
Load from GitHub — Import existing templates from repositories with live search
Edit visually — Use the tabbed interface to configure:
- Metadata — Name, title, description, tags, owner
- Parameters — Input fields with validation, UI widgets, and conditional logic
- Steps — Scaffolder actions (fetch, publish, debug, custom)
- Output — Links displayed after template execution
Validate anytime — Click "Validate" to check for errors, warnings, and issues; clickable results navigate directly to the problem
Preview YAML — See live YAML output and edit directly if needed
Visualize flow — View execution flow as a directed graph
Preview end-user experience — See what developers will see
Save to GitHub — Push templates back to repositories with pre-push validation

Development

To develop the plugin locally:

cd plugins/backstage-template-builder
yarn install
yarn start

This will start the plugin in development mode at http://localhost:3000 using Backstage's dev utilities.

Building

To build the plugin:

cd plugins/backstage-template-builder
yarn build

The build output will be in the dist/ directory.

Architecture

Frontend-only plugin — No backend services required
State management — React Context + useReducer
YAML generation — js-yaml library
Template validation — Client-side validation with smart navigation to issues
Drag-and-drop — @dnd-kit for parameter and step reordering
UI components — Radix UI primitives with Tailwind CSS
GitHub integration — Direct API calls from the browser with live search (no proxy needed)

Status

Early release / actively maintained

The plugin is functional and ready for use in Backstage instances. APIs and UI may evolve based on feedback.

Contributions, ideas, and feedback are welcome!

Screenshots

Visual Template Editor

Build templates using structured forms across four main sections:

Metadata - Define template identity, owner, and tags

Parameters - Create input fields with validation and UI widgets

Steps - Configure scaffolder actions with detailed inputs

Output - Define links shown after template execution

Execution Flow Visualization

See how your scaffolder steps execute in a visual flow diagram

End-User Preview

Preview what developers will see when using your template

Form View

Review Step

Completion

Troubleshooting

Plugin not appearing in Backstage

Verify installation:

# Check that the plugin is in your workspace
ls plugins/backstage-template-builder

# Verify it's listed in package.json
grep "backstage-template-builder" packages/app/package.json

Clear cache and rebuild:
```
yarn clean
yarn install
yarn dev
```
Check browser console for any error messages

Build errors

If you get TypeScript compilation errors:

cd plugins/backstage-template-builder
rm -rf dist dist-types node_modules
yarn install
yarn build

GitHub integration issues

"Resource not accessible": Token needs repo scope (Classic) or Contents R/W + Metadata R (Fine-grained)
Token not persisting: Check that browser localStorage is enabled
CORS errors: The plugin makes direct API calls to GitHub - ensure your browser allows this

Roadmap

Potential future enhancements:

Backend service integration for template validation
Publish templates directly to Backstage catalog
Multi-user collaboration features
Migration to Material-UI for native Backstage styling
Template versioning and change history
Permission/RBAC integration

Contributing

Contributions, ideas, and feedback are welcome!

Please open an issue to discuss larger changes before submitting a PR.

License

MIT

Name		Name	Last commit message	Last commit date
.github/assets		.github/assets
plugins/backstage-template-builder		plugins/backstage-template-builder
.gitignore		.gitignore
BACKSTAGE-DEPLOYMENT.md		BACKSTAGE-DEPLOYMENT.md
CLAUDE.md		CLAUDE.md
DEPLOYMENT-COMPARISON.md		DEPLOYMENT-COMPARISON.md
LICENSE		LICENSE
QUAY-DEPLOYMENT.md		QUAY-DEPLOYMENT.md
QUICK-START.md		QUICK-START.md
README.md		README.md
RHDH-DEPLOYMENT.md		RHDH-DEPLOYMENT.md
balajisiva-backstage-plugin-template-builder.yaml		balajisiva-backstage-plugin-template-builder.yaml
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation