Vega Bootstrap

Table of Contents

• Introduction
• Architecture
• Get started
  • Pre-requisite
  • How to create the input
  • How to run it
    • Build a single component
    • Build all components (recommended)
    • Watch mode
  • Development workflow
  • Adding new test cases
  • Symlink with existing app for testing
• Available scripts

Introduction

Vega Bootstrap is a code-generation tool that produces stand-alone, framework-specific Vega component modules from a single TypeScript input config. It eliminates the duplicate effort of writing the same component for VanillaJS, Angular, React, and Vue.

Modify the input config once → all four framework outputs are regenerated automatically.

Supported output frameworks:

| Framework | Output files | |-----------|-------------| | VanillaJS | <component>.html | | Angular | <component>.html + <component>.ts | | React | <component>.jsx | | Vue | <component>.vue |

Architecture

Two diagrams describe the system: the overall pipeline flow and the per-framework builder breakdown.

Pipeline

flowchart LR
    In(["<component>.input.ts"])

    subgraph Validate["① Validate"]
        V["State · undefined ref · duplicate def · reserved name\nAction · undefined ref · duplicate def · reserved name\nView · duplicate node ID"]
    end

    subgraph Preprocess["② Preprocess"]
        P["VanillaJS: auto node IDs · link view → state & action\nAll frameworks: AST prefill for state, action & declarations"]
    end

    subgraph BuildPhase["③ Build"]
        B["Import · View · State · Action · Other blocks\n↕ per framework — see builder matrix below"]
    end

    subgraph Assemble["④ Assemble"]
        A["Apply framework template → Prettier format"]
    end

    In ==> Validate ==> Preprocess ==> BuildPhase ==> Assemble
    Assemble --> o1["VanillaJS\ncomponent.html"]
    Assemble --> o2["Angular\ncomponent.html + component.ts"]
    Assemble --> o3["React\nComponent.jsx"]
    Assemble --> o4["Vue\nComponent.vue"]

Builder Matrix

Each build block has a framework-specific implementation. The table below maps block type → framework output.

block
  columns 5

  hd["Builder"]
  vjs["VanillaJS"]
  ng["Angular"]
  rx["React"]
  vue["Vue"]

  imp["Import\nBlock"]
  imp_v["static script\n& style tags"]
  imp_n["@angular/core\n+ auto-detected\nVega API imports"]
  imp_r["Vega component\nimports"]
  imp_u["Vega component\nimports"]

  viw["View\nBlock"]
  viw_v["HTML attributes\n(no state/action\nbinding)"]
  viw_n["[prop] state bind\n(event) action bind"]
  viw_r["JSX prop &\nevent binding"]
  viw_u[":prop bind\n@event bind"]

  sta["State\nBlock"]
  sta_v["State object\ngetter / setter\nDOM update on set"]
  sta_n["Class property\nwith TS type"]
  sta_r["state { }\nin constructor"]
  sta_u["data()\nreturn { }"]

  act["Action\nBlock"]
  act_v["Action object\n+ addEventListener"]
  act_n["Class methods"]
  act_r["Class methods"]
  act_u["methods: { }"]

  oth["Other\nBlock"]
  oth_v["Node Ref Block\nconst el =\ngetElementById()"]
  oth_n["Regex class fields\nngOnInit() setup"]
  oth_r["componentDidMount()\nsetup code"]
  oth_u["created()\nsetup code"]

  classDef fw fill:#1a5276,color:#fff,stroke:#154360;
  classDef kind fill:#1e8449,color:#fff,stroke:#196f3d;
  class vjs,ng,rx,vue fw
  class imp,viw,sta,act,oth kind
  style hd fill:#212121,color:#fff,stroke:#000;

Original draw.io source: docs/vega-bootstrap.drawio

Get started

Pre-requisite

yarn install

How to create the input

Define a TypeScript input config file under input/. This is the single source of truth — the generator reads it and produces all framework outputs:

// my-component.input.ts
import { ComponentInput } from 'src/types/component/component';

const MyComponentInput: ComponentInput = {
  name: 'MyComponent',
  view: {
    viewNodes: [
      // view nodes composing the component HTML structure
    ],
  },
  state: {
    stateNodes: [
      // state nodes managing component state
    ],
  },
  action: {
    actionNodes: [
      // action nodes handling user interactions
    ],
  },
};

Tip: Due to a known TypeScript limitation, nested object types in literals are not inferred automatically. Cast explicitly to get type hints:

{ type: 'vega-flex' } as ComponentViewNode

How to run it

Build a single component

yarn build \
  -c <input_config_path> \
  -vanilla <vanilla_js_output_path> \
  -angular <angular_output_path> \
  -react   <react_output_path> \
  -vue     <vue_output_path>

Example:

yarn build \
  -c ./input/simple-component.input.ts \
  -vanilla ./output/vanilla-js \
  -angular ./output/angular \
  -react   ./output/react \
  -vue     ./output/vue

Run yarn help to see all CLI options.

Build all components (recommended)

⚠️ Always use build-all:remote when preparing changes for CI.

• build-all:local writes to ./output/ only — this output is not checked by CI.
• build-all:remote writes directly into the playground apps (vega-playground/vega-*-hello-world/) which the Cypress integration and SRI tests validate.

Forgetting to run build-all:remote and commit the results will cause integration test failures in the pipeline even when the generator logic is correct.

# Local preview only (writes to ./output/)
yarn build-all:local

# Required before committing (writes to ../vega-playground/)
yarn build-all:remote

Watch mode

For iterative development on a single component, pass -w to auto-regenerate on file save:

yarn build \
  -c ./input/my-component.input.ts \
  -vanilla ./output/vanilla-js \
  -angular ./output/angular \
  -react   ./output/react \
  -vue     ./output/vue \
  -w

Note: watch mode only targets one component at a time. Always run build-all:remote for a final sync before committing.

Development workflow

1. Edit the .input.ts file under input/.
2. Iterate locally using watch mode (-w) or build-all:local to preview output under ./output/.
3. Run pre-release checks to confirm the code is ready:

   yarn pre-release   # runs: jest + tsc --noEmit + eslint + prettier

4. Sync to the playground so the CI integration tests have up-to-date files:

   yarn build-all:remote

5. Commit everything together — generator source changes and all generated playground files in a single commit.

Adding new test cases

When you add a new input or change generator logic, unit test snapshots under tst/output/expected/ may need to be updated:

yarn rectify-test   # promotes tst/output/actual/ → tst/output/expected/

Review the diff carefully before committing to confirm the snapshot changes are intentional.

Symlink with existing app for testing

You can symlink ./output/ directly into a playground app to see live changes without running build-all:remote:

cd vega-playground/vega-angular-hello-world/src/app
ln -s ../../../../vega-bootstrap/output/angular/ESS ESS

Import the linked component in app.module.ts:

import { EssHomePage } from './ESS/ess-home-page';

@NgModule({
  declarations: [AppComponent, EssHomePage],
})
export class AppModule {}

Use it in a template:

<ess-home-page></ess-home-page>

Available scripts

| Script | Description | |--------|-------------| | yarn build | Generate output for a single component (see yarn help for CLI flags) | | yarn build-all:local | Generate all components → ./output/ (local preview only) | | yarn build-all:remote | Generate all components → ../vega-playground/ (required before committing) | | yarn test | Run Jest unit tests | | yarn rectify-test | Promote actual test output to expected snapshots | | yarn type-check | TypeScript type-check without emitting | | yarn linter | ESLint + Prettier check (--max-warnings 0) | | yarn pre-release | Full pre-release gate: test + type-check + linter |