Generator Superset

Generator Superset is a Yeoman generator that provides scaffolding capabilities for creating Superset visualization plugins and packages. It automates the creation of properly structured React-based chart components with TypeScript support, complete with testing infrastructure, build configuration, and development tooling.

Package Information

• Package Name: @superset-ui/generator-superset
• Package Type: npm
• Language: JavaScript
• Installation: npm install -g yo && npm install -g @superset-ui/generator-superset

Core Imports

The package provides Yeoman generators that are executed through the yo command-line tool:

yo @superset-ui/superset

The generators extend the yeoman-generator base class and are not directly imported as modules.

Basic Usage

# Install prerequisites
npm install -g yo
npm install -g @superset-ui/generator-superset

# Create a new directory for your plugin
mkdir my-superset-plugin
cd my-superset-plugin

# Run the generator
yo @superset-ui/superset

# Follow the interactive prompts to configure your plugin

The generator will prompt for:

• Package name (defaults to directory name in kebab-case)
• Plugin display name (formatted as Start Case)
• Package description
• Chart type (regular or time-series)

Architecture

Generator Superset follows the Yeoman generator architecture with two main components:

• App Generator: Main entry point that provides welcome messages and coordinates with sub-generators
• Plugin-Chart Generator: Core generator that handles file creation and templating for chart plugins
• Template System: Comprehensive set of ERB templates for scaffolding complete plugin projects
• Prompt System: Interactive command-line interface for gathering user preferences

The generated projects follow Superset's conventions for plugin structure, using TypeScript, React, and modern build tooling.

Capabilities

App Generator

Main generator class that serves as the entry point for the scaffolding process.

class AppGenerator extends Generator {
  async prompting(): Promise<void>;
  configuring(): void;
}

Methods:

• prompting() - Displays welcome message and sets up options
• configuring() - Composes with the plugin-chart generator

Options:

• skipInstall - Boolean flag to skip npm package installation

Plugin-Chart Generator

Core generator that creates the complete chart plugin scaffold with interactive prompts and file generation.

class PluginChartGenerator extends Generator {
  async prompting(): Promise<void>;
  writing(): void;
}

Methods:

• prompting() - Gathers user input through interactive prompts
• writing() - Generates all scaffold files from templates

Prompt Configuration:

interface PromptAnswers {
  packageName: string;    // Package name in kebab-case
  pluginName: string;     // Display name in Start Case
  description: string;    // Package description
  chartType: 'regular' | 'timeseries';  // Chart type selection
}

Generated File Structure: The generator creates a complete plugin project with the following files:

• .gitignore - Git ignore configuration
• babel.config.js - Babel transpilation configuration
• jest.config.js - Jest testing configuration
• package.json - NPM package configuration
• package-lock.json - NPM dependency lock file
• README.md - Project documentation
• tsconfig.json - TypeScript configuration
• src/index.ts - Main plugin export
• src/plugin/buildQuery.ts - Query building logic
• src/plugin/controlPanel.ts - Chart control panel configuration
• src/plugin/index.ts - Plugin registration
• src/plugin/transformProps.ts - Data transformation logic
• src/types.ts - TypeScript type definitions
• src/[PluginName].tsx - Main React component
• test/index.test.ts - Main test file
• test/__mocks__/mockExportString.js - Test mocks
• test/plugin/buildQuery.test.ts - Query builder tests
• test/plugin/transformProps.test.ts - Transform logic tests
• types/external.d.ts - External type definitions
• src/images/thumbnail.png - Plugin thumbnail image

Template Processing

The generator uses ERB-style templates with parameter substitution for dynamic file generation.

interface TemplateParams {
  packageName: string;     // User-provided package name
  pluginName: string;      // User-provided plugin display name
  description: string;     // User-provided description
  chartType: string;       // Selected chart type
  packageLabel: string;    // Generated UpperCamelCase class name
}

Template Operations:

• Files with .erb extension are processed with template parameters
• Static files are copied directly without processing
• Dynamic naming is applied to component files based on packageLabel

Dependencies

The generated projects include specific dependencies for Superset plugin development:

Runtime Dependencies:

interface GeneratorDependencies {
  chalk: string;           // Terminal styling (^4.0.0)
  lodash: string;          // Utility functions (^4.17.11)
  "yeoman-generator": string;  // Generator framework (^4.0.0)
  yosay: string;           // Welcome messages (^2.0.2)
}

Generated Project Dependencies:

• React and TypeScript for component development
• Jest and testing utilities for test infrastructure
• Babel for transpilation
• Webpack-based build system integration

Usage Examples

Basic Plugin Generation

# Create new plugin directory
mkdir superset-plugin-chart-my-chart
cd superset-plugin-chart-my-chart

# Run generator
yo @superset-ui/superset

# Example prompt responses:
# Package name: superset-plugin-chart-my-chart
# Plugin name: My Chart
# Description: Custom chart plugin for Superset
# Chart type: Regular chart

Programmatic Usage (Advanced)

While primarily designed for CLI usage, the generators can be composed programmatically:

const Generator = require('yeoman-generator');
const AppGenerator = require('@superset-ui/generator-superset/generators/app');

class CustomGenerator extends Generator {
  configuring() {
    this.composeWith(AppGenerator, {
      skipInstall: true
    });
  }
}

Error Handling

The generators inherit standard Yeoman error handling behavior:

• Invalid directory permissions will cause the generator to fail
• Missing dependencies (Node.js, npm) will prevent execution
• Template processing errors are propagated to the Yeoman framework
• File system errors during writing phase will terminate the generator

Common resolution steps:

• Ensure proper directory permissions
• Verify Node.js and npm are installed and accessible
• Check available disk space for file generation

Engine Requirements

• Node.js environment (required for Yeoman)
• npm >= 4.0.0 (specified in package.json engines)
• Yeoman CLI tool (yo) must be globally installed