Backstage Integration

The @httpdss/plugin-scaffolder-backend-module-structkit plugin adds StructKit as native Backstage scaffolder actions plus a custom field extension, so template authors can scaffold projects with StructKit directly from Backstage software templates.

What it provides

The plugin adds multiple StructKit actions to Backstage software templates:

structkit:generate — generate code from structures.
structkit:list — list available structures.
structkit:info — get structure details.
structkit:vars — get required template variables.
structkit:validate — validate structure files.

A frontend StructKitPicker field extension lets template authors select structures from a dropdown, discover available structures dynamically, query required variables before generation, validate structures before use, and generate files into the workspace.

Source repository: httpdss/backstage-plugin-structkit.

Alongside the scaffolder packages, the frontend @httpdss/plugin-structkit package provides a StructKitCard catalog entity card showing which structure generated the component, documentation links, validation, and drift detection; isStructkitAvailable is available for EntitySwitch. The backend @httpdss/plugin-structkit-backend package provides the card's POST /api/structkit/validate endpoint, which runs the structkit CLI on the backend host.

Catalog annotations: structkit.io/structure, structkit.io/struct-file, and structkit.io/source.

catalog-info.yamlyaml

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-python-service
  annotations:
    structkit.io/structure: project/python
    structkit.io/struct-file: .structkit.yaml
    structkit.io/source: https://github.com/httpdss/structkit
spec:
  type: service
  lifecycle: production
  owner: platform-team

Prerequisites

The structkit CLI must be installed and available on the PATH of the Backstage backend host. Install it and verify:

Using npmbash

npm install -g structkit

Using yarnbash

yarn global add structkit

Verify installationbash

structkit --version

Install

From your Backstage root directory, add the package to the backend:

Terminalbash

yarn --cwd packages/backend add @httpdss/plugin-scaffolder-backend-module-structkit

For the new backend system (recommended), register the module:

Backend registrationtypescript

// packages/backend/src/index.ts
import { createBackend } from '@backstage/backend-defaults';

const backend = createBackend();

// ... other plugins ...

backend.add(import('@backstage/plugin-scaffolder-backend'));
backend.add(
  import('@httpdss/plugin-scaffolder-backend-module-structkit'),
);

backend.start();

Verify the actions are registered:

Verify actionsbash

yarn backstage-cli info --actions | grep structkit

Custom binary path

If structkit is not on PATH, point the plugin at a custom binary in app-config.yaml:

app-config.yamlyaml

structkit:
  binaryPath: /custom/path/to/structkit

Usage in a template

A basic example using a named structure, generating files into the workspace and publishing them:

Templateyaml

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: my-app-template
  title: My App Template
  description: Create a new app with StructKit
spec:
  owner: platform-team
  type: service

  parameters:
    - title: Project Information
      required:
        - name
      properties:
        name:
          title: Name
          type: string

  steps:
    - id: structkit-generate
      name: Generate Project Structure
      action: structkit:generate
      input:
        structure: nextjs-app
        outputPath: .
        vars:
          project_name: ${{ parameters.name }}
        noHooks: true

    - id: publish
      name: Publish to GitHub
      action: publish:github
      input:
        allowedHosts: ['github.com']
        description: Generated with StructKit
        repoUrl: ${{ parameters.repoUrl }}

  output:
    links:
      - title: Repository
        url: ${{ steps.publish.output.remoteUrl }}

The structkit:generate action accepts structure or structFile (one of the two is required, not both), plus outputPath, vars, dryRun, and noHooks (default true for safety). Use the structkit:list, structkit:info, and structkit:vars actions to discover structures and their variables before generating.

StructKitPicker field extension

The @httpdss/plugin-scaffolder-field-structkit package provides a custom field for selecting StructKit structures in template forms.

Installbash

yarn --cwd packages/app add @httpdss/plugin-scaffolder-field-structkit

// packages/app/src/scaffolder/index.tsx
import { ScaffolderFieldExtensions } from '@backstage/plugin-scaffolder-react';
import { StructKitPickerFieldExtension } from '@httpdss/plugin-scaffolder-field-structkit';

export const scaffolderPlugin = ScaffolderPage.create({
  components: {
    FieldExtensions: (
      <ScaffolderFieldExtensions>
        <StructKitPickerFieldExtension />
      </ScaffolderFieldExtensions>
    ),
  },
});

Then use ui:field: StructKitPicker in a template, either from a static list or dynamically from a structkit:list step:

Static dropdownyaml

parameters:
  - title: Choose Structure
    properties:
      structure:
        title: StructKit Structure
        type: string
        ui:field: StructKitPicker
        ui:options:
          structures:
            - name: nextjs-app
              description: Next.js application
            - name: react-component
              description: React component library

Docs

See the plugin README for complete action inputs, outputs, and example templates, including custom-file and dynamic-structure variants.

Hermes Agent

StructKit Skill