Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
113 lines (85 loc) · 3.32 KB

ARCHITECTURE.md

File metadata and controls

113 lines (85 loc) · 3.32 KB

Example Generator - Architecture

Overview

The Example Generator automatically generates framework-specific example code from Storybook stories. It uses an interface-based architecture that makes it easy to add support for new frameworks.

Directory Structure

example-generator/
├── src/
│   ├── index.ts                    # Main entry point
│   ├── interfaces.ts               # Core interfaces
│   ├── types.ts                    # Type definitions
│   ├── parser.ts                   # Story parsing logic
│   ├── generators/                 # Framework-specific generators
│   │   ├── html-generator.ts
│   │   ├── react-generator.ts
│   │   ├── angular-generator.ts
│   │   └── vue-generator.ts
│   ├── formatters/                 # Code formatters
│   │   ├── html-formatter.ts
│   │   ├── react-formatter.ts
│   │   ├── angular-formatter.ts
│   │   └── vue-formatter.ts
│   └── utils/                      # Shared utilities
│       ├── string-utils.ts
│       └── file-updater.ts
└── package.json

Core Concepts

Generators

Each framework has a generator that implements the IExampleGenerator interface:

  • HTMLExampleGenerator - Generates vanilla HTML/Web Component examples
  • ReactExampleGenerator - Generates React/TSX examples
  • AngularExampleGenerator - Generates Angular examples
  • VueExampleGenerator - Generates Vue examples

Formatters

Formatters handle converting component data to framework-specific code:

  • Convert props to correct syntax (e.g., checked → [checked] in Angular)
  • Generate event handlers
  • Format imports and component usage

File Updater

Updates example app files using marked regions:

<!-- <AUTO-GENERATED-COMPONENTS> -->
  <!-- Generated code appears here -->
<!-- </AUTO-GENERATED-COMPONENTS> -->

User code outside these markers is preserved.

How It Works

  1. Extract: Parse Storybook stories to extract component information
    • Supports both CSF2 (function exports) and CSF3 (object with render function)
    • Example CSF3: export const Default: StoryObj = { render: (args) => html... }
  2. Format: Use formatters to convert data to framework-specific code
  3. Update: Inject generated code into example apps using marked regions

Adding a New Framework

  1. Create a Formatter in src/formatters/
  2. Create a Generator in src/generators/
  3. Register the generator in src/index.ts

Example:

// formatters/svelte-formatter.ts
export class SvelteCodeFormatter implements ICodeFormatter {
  formatComponent(component: ComponentInfo): string {
    // Convert to Svelte syntax
  }
}

// generators/svelte-generator.ts
export class SvelteExampleGenerator implements IExampleGenerator {
  generate(components: ComponentInfo[], config: GeneratorConfig): GenerationResult {
    // Generate Svelte examples
  }
}

// index.ts
const generators = [
  new HTMLExampleGenerator(),
  new ReactExampleGenerator(),
  new SvelteExampleGenerator()  // Add new generator
];

Running

cd example-generator
pnpm run start       # Generate examples once

Output updates all example apps in examples/ directory.

For usage instructions, see README.md