0
# Generator Superset
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @superset-ui/generator-superset
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install -g yo && npm install -g @superset-ui/generator-superset`
10

11
## Core Imports
12

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

15
```bash
16
yo @superset-ui/superset
17
```
18

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

21
## Basic Usage
22

23
```bash
24
# Install prerequisites
25
npm install -g yo
26
npm install -g @superset-ui/generator-superset
27

28
# Create a new directory for your plugin
29
mkdir my-superset-plugin
30
cd my-superset-plugin
31

32
# Run the generator
33
yo @superset-ui/superset
34

35
# Follow the interactive prompts to configure your plugin
36
```
37

38
The generator will prompt for:
39
- Package name (defaults to directory name in kebab-case)
40
- Plugin display name (formatted as Start Case)
41
- Package description
42
- Chart type (regular or time-series)
43

44
## Architecture
45

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

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

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

55
## Capabilities
56

57
### App Generator
58

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

61
```javascript { .api }
62
class AppGenerator extends Generator {
63
  async prompting(): Promise<void>;
64
  configuring(): void;
65
}
66
```
67

68
**Methods:**
69
- `prompting()` - Displays welcome message and sets up options
70
- `configuring()` - Composes with the plugin-chart generator
71

72
**Options:**
73
- `skipInstall` - Boolean flag to skip npm package installation
74

75
### Plugin-Chart Generator
76

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

79
```javascript { .api }
80
class PluginChartGenerator extends Generator {
81
  async prompting(): Promise<void>;
82
  writing(): void;
83
}
84
```
85

86
**Methods:**
87
- `prompting()` - Gathers user input through interactive prompts
88
- `writing()` - Generates all scaffold files from templates
89

90
**Prompt Configuration:**
91
```javascript { .api }
92
interface PromptAnswers {
93
  packageName: string;    // Package name in kebab-case
94
  pluginName: string;     // Display name in Start Case
95
  description: string;    // Package description
96
  chartType: 'regular' | 'timeseries';  // Chart type selection
97
}
98
```
99

100
**Generated File Structure:**
101
The generator creates a complete plugin project with the following files:
102
- `.gitignore` - Git ignore configuration
103
- `babel.config.js` - Babel transpilation configuration
104
- `jest.config.js` - Jest testing configuration
105
- `package.json` - NPM package configuration
106
- `package-lock.json` - NPM dependency lock file
107
- `README.md` - Project documentation
108
- `tsconfig.json` - TypeScript configuration
109
- `src/index.ts` - Main plugin export
110
- `src/plugin/buildQuery.ts` - Query building logic
111
- `src/plugin/controlPanel.ts` - Chart control panel configuration
112
- `src/plugin/index.ts` - Plugin registration
113
- `src/plugin/transformProps.ts` - Data transformation logic
114
- `src/types.ts` - TypeScript type definitions
115
- `src/[PluginName].tsx` - Main React component
116
- `test/index.test.ts` - Main test file
117
- `test/__mocks__/mockExportString.js` - Test mocks
118
- `test/plugin/buildQuery.test.ts` - Query builder tests
119
- `test/plugin/transformProps.test.ts` - Transform logic tests
120
- `types/external.d.ts` - External type definitions
121
- `src/images/thumbnail.png` - Plugin thumbnail image
122

123
### Template Processing
124

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

127
```javascript { .api }
128
interface TemplateParams {
129
  packageName: string;     // User-provided package name
130
  pluginName: string;      // User-provided plugin display name
131
  description: string;     // User-provided description
132
  chartType: string;       // Selected chart type
133
  packageLabel: string;    // Generated UpperCamelCase class name
134
}
135
```
136

137
**Template Operations:**
138
- Files with `.erb` extension are processed with template parameters
139
- Static files are copied directly without processing
140
- Dynamic naming is applied to component files based on packageLabel
141

142
### Dependencies
143

144
The generated projects include specific dependencies for Superset plugin development:
145

146
**Runtime Dependencies:**
147
```javascript { .api }
148
interface GeneratorDependencies {
149
  chalk: string;           // Terminal styling (^4.0.0)
150
  lodash: string;          // Utility functions (^4.17.11)
151
  "yeoman-generator": string;  // Generator framework (^4.0.0)
152
  yosay: string;           // Welcome messages (^2.0.2)
153
}
154
```
155

156
**Generated Project Dependencies:**
157
- React and TypeScript for component development
158
- Jest and testing utilities for test infrastructure
159
- Babel for transpilation
160
- Webpack-based build system integration
161

162
## Usage Examples
163

164
### Basic Plugin Generation
165

166
```bash
167
# Create new plugin directory
168
mkdir superset-plugin-chart-my-chart
169
cd superset-plugin-chart-my-chart
170

171
# Run generator
172
yo @superset-ui/superset
173

174
# Example prompt responses:
175
# Package name: superset-plugin-chart-my-chart
176
# Plugin name: My Chart
177
# Description: Custom chart plugin for Superset
178
# Chart type: Regular chart
179
```
180

181
### Programmatic Usage (Advanced)
182

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

185
```javascript
186
const Generator = require('yeoman-generator');
187
const AppGenerator = require('@superset-ui/generator-superset/generators/app');
188

189
class CustomGenerator extends Generator {
190
  configuring() {
191
    this.composeWith(AppGenerator, {
192
      skipInstall: true
193
    });
194
  }
195
}
196
```
197

198
## Error Handling
199

200
The generators inherit standard Yeoman error handling behavior:
201

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

207
Common resolution steps:
208
- Ensure proper directory permissions
209
- Verify Node.js and npm are installed and accessible
210
- Check available disk space for file generation
211

212
## Engine Requirements
213

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