0
# Plugin Development
1

2
Plugin creation and management system for extending Taro functionality with custom build processes and platform support.
3

4
## Capabilities
5

6
### Plugin Class
7

8
Main class for creating Taro plugins with template scaffolding and configuration management.
9

10
```typescript { .api }
11
/**
12
 * Plugin creation and management class extending Creator
13
 */
14
class Plugin extends Creator {
15
  conf: IPluginConf;
16
  
17
  /**
18
   * Initialize plugin creator with configuration
19
   * @param options - Plugin configuration options
20
   */
21
  constructor(options: IPluginConf);
22
  
23
  /**
24
   * Create plugin from template with scaffolding
25
   * @returns Promise that resolves when plugin creation completes
26
   */
27
  create(): Promise<void>;
28
  
29
  /**
30
   * Get CLI version for plugin metadata
31
   * @returns CLI version string
32
   */
33
  getCliVersion(): string;
34
}
35
```
36

37
### Plugin Configuration
38

39
Complete configuration interface for plugin creation with all supported options.
40

41
```typescript { .api }
42
/**
43
 * Plugin configuration interface
44
 */
45
interface IPluginConf {
46
  /** Name of the plugin */
47
  pluginName: string;
48
  /** Plugin type */
49
  type: string;
50
  /** Plugin description */
51
  description?: string;
52
  /** Directory where plugin will be created */
53
  projectDir: string;
54
  /** Project name (derived from directory) */
55
  projectName: string;
56
  /** Template to use for plugin creation */
57
  template: string;
58
  /** CLI version */
59
  version: string;
60
}
61
```
62

63
**Usage Examples:**
64

65
```typescript
66
import { Plugin } from "@tarojs/cli";
67

68
// Create a platform plugin
69
const platformPlugin = new Plugin({
70
  pluginName: 'my-platform-plugin',
71
  type: 'platform',
72
  description: 'Custom platform support for Taro',
73
  projectDir: '/path/to/my-platform-plugin',
74
  projectName: 'my-platform-plugin',
75
  template: 'platform',
76
  version: '4.1.6'
77
});
78

79
await platformPlugin.create();
80

81
// Create a build plugin
82
const buildPlugin = new Plugin({
83
  pluginName: 'custom-build-plugin',
84
  type: 'build',
85
  description: 'Custom build process plugin',
86
  projectDir: '/path/to/build-plugin',
87
  projectName: 'custom-build-plugin',
88
  template: 'build',
89
  version: '4.1.6'
90
});
91

92
await buildPlugin.create();
93
```
94

95
### Plugin Types
96

97
Different types of plugins supported by the Taro ecosystem with their specific roles.
98

99
```typescript { .api }
100
/**
101
 * Supported plugin types
102
 */
103
type PluginType = 
104
  | 'platform'      // Platform-specific compilation support
105
  | 'build'         // Build process customization
106
  | 'framework'     // Framework integration
107
  | 'transform'     // Code transformation
108
  | 'analysis'      // Code analysis and linting
109
  | 'deploy'        // Deployment automation
110
  | 'dev-tools';    // Development tooling
111

112
/**
113
 * Plugin type configurations and capabilities
114
 */
115
interface PluginTypeConfig {
116
  platform: {
117
    purpose: 'Add support for new target platforms';
118
    hooks: ['onBuildStart', 'onBuildFinish', 'onGenerateProjectConfig'];
119
    examples: ['@tarojs/plugin-platform-weapp', '@tarojs/plugin-platform-h5'];
120
  };
121
  build: {
122
    purpose: 'Customize build pipeline and webpack configuration';
123
    hooks: ['onBuildStart', 'modifyWebpackChain', 'onBuildFinish'];
124
    examples: ['@tarojs/plugin-terser', '@tarojs/plugin-csso'];
125
  };
126
  framework: {
127
    purpose: 'Add support for new frontend frameworks';
128
    hooks: ['onParseCreateElement', 'onBuildStart'];
129
    examples: ['@tarojs/plugin-framework-react', '@tarojs/plugin-framework-vue3'];
130
  };
131
}
132
```
133

134
### Plugin Templates
135

136
Available plugin templates for different plugin types and their structures.
137

138
```typescript { .api }
139
/**
140
 * Plugin template structure
141
 */
142
interface PluginTemplate {
143
  'src/': {
144
    'index.ts': 'Main plugin entry point';
145
    'types.ts': 'Plugin type definitions';
146
    'utils.ts': 'Plugin utility functions';
147
  };
148
  'package.json': 'Plugin package configuration';
149
  'README.md': 'Plugin documentation';
150
  'tsconfig.json': 'TypeScript configuration';
151
  '.gitignore': 'Git ignore rules';
152
}
153

154
/**
155
 * Available plugin templates
156
 */
157
interface PluginTemplates {
158
  platform: 'Template for platform plugins';
159
  build: 'Template for build process plugins';
160
  framework: 'Template for framework integration plugins';
161
  transform: 'Template for code transformation plugins';
162
  default: 'Basic plugin template';
163
}
164
```
165

166
### Plugin API Interface
167

168
Standard interface that Taro plugins must implement for integration with the build system.
169

170
```typescript { .api }
171
/**
172
 * Standard Taro plugin interface
173
 */
174
interface TaroPlugin {
175
  /** Plugin name */
176
  name: string;
177
  /** Plugin version */
178
  version?: string;
179
  /** Plugin options */
180
  options?: Record<string, any>;
181
  
182
  /**
183
   * Plugin initialization function
184
   * @param api - Taro plugin API
185
   * @param options - Plugin configuration options
186
   */
187
  (api: PluginAPI, options?: Record<string, any>): void;
188
}
189

190
/**
191
 * Plugin API provided by Taro to plugins
192
 */
193
interface PluginAPI {
194
  /** Register hook listeners */
195
  onBuildStart(callback: () => void): void;
196
  onBuildFinish(callback: () => void): void;
197
  onGenerateProjectConfig(callback: (config: any) => any): void;
198
  
199
  /** Modify build configuration */
200
  modifyWebpackConfig(callback: (config: any) => any): void;
201
  modifyBuildAssets(callback: (assets: any) => any): void;
202
  
203
  /** Utility functions */
204
  getProjectName(): string;
205
  getProjectPath(): string;
206
  getCurrentPlatform(): string;
207
}
208
```
209

210
### Plugin Development Workflow
211

212
Step-by-step guide for developing custom Taro plugins.
213

214
```typescript { .api }
215
/**
216
 * Plugin development workflow steps
217
 */
218
interface PluginDevelopmentWorkflow {
219
  1: 'Define plugin purpose and type';
220
  2: 'Create plugin using Plugin class or template';
221
  3: 'Implement plugin interface and hooks';
222
  4: 'Test plugin with sample Taro project';
223
  5: 'Package and publish plugin to npm';
224
  6: 'Document plugin usage and configuration';
225
}
226

227
/**
228
 * Plugin testing utilities
229
 */
230
interface PluginTesting {
231
  /** Create test project for plugin validation */
232
  createTestProject(pluginPath: string): Promise<void>;
233
  /** Run build with plugin enabled */
234
  testBuild(platform: string): Promise<BuildResult>;
235
  /** Validate plugin output */
236
  validateOutput(expectedFiles: string[]): boolean;
237
}
238
```
239

240
### Plugin Hooks System
241

242
Comprehensive hook system for plugin integration at different build stages.
243

244
```typescript { .api }
245
/**
246
 * Available plugin hooks in Taro build lifecycle
247
 */
248
interface PluginHooks {
249
  /** Called before build process starts */
250
  onBuildStart: (callback: () => void) => void;
251
  
252
  /** Called after build process completes */
253
  onBuildFinish: (callback: (buildResult: BuildResult) => void) => void;
254
  
255
  /** Called when generating project configuration */
256
  onGenerateProjectConfig: (callback: (config: ProjectConfig) => ProjectConfig) => void;
257
  
258
  /** Called to modify webpack configuration */
259
  modifyWebpackConfig: (callback: (config: WebpackConfig) => WebpackConfig) => void;
260
  
261
  /** Called to modify build assets */
262
  modifyBuildAssets: (callback: (assets: BuildAssets) => BuildAssets) => void;
263
  
264
  /** Called to modify app entry */
265
  modifyAppEntry: (callback: (entry: string) => string) => void;
266
  
267
  /** Called during code transformation */
268
  onParseCreateElement: (callback: (nodePath: NodePath) => void) => void;
269
}
270

271
/**
272
 * Build result interface for hook callbacks
273
 */
274
interface BuildResult {
275
  success: boolean;
276
  platform: string;
277
  outputPath: string;
278
  duration: number;
279
  errors?: string[];
280
  warnings?: string[];
281
}
282
```
283

284
### Plugin Configuration Schema
285

286
Schema for plugin configuration validation and documentation.
287

288
```typescript { .api }
289
/**
290
 * Plugin configuration schema
291
 */
292
interface PluginConfigSchema {
293
  /** Plugin identifier */
294
  name: string;
295
  /** Plugin configuration options */
296
  options?: {
297
    [key: string]: {
298
      type: 'string' | 'boolean' | 'number' | 'object' | 'array';
299
      required?: boolean;
300
      default?: any;
301
      description: string;
302
    };
303
  };
304
}
305

306
/**
307
 * Example plugin configuration
308
 */
309
const examplePluginConfig: PluginConfigSchema = {
310
  name: 'my-custom-plugin',
311
  options: {
312
    enabled: {
313
      type: 'boolean',
314
      default: true,
315
      description: 'Enable or disable the plugin'
316
    },
317
    outputPath: {
318
      type: 'string',
319
      required: true,
320
      description: 'Output directory for plugin files'
321
    },
322
    transforms: {
323
      type: 'array',
324
      default: [],
325
      description: 'List of transformations to apply'
326
    }
327
  }
328
};
329
```
330

331
### Plugin Publishing
332

333
Guidelines and utilities for publishing plugins to npm registry.
334

335
```typescript { .api }
336
/**
337
 * Plugin publishing checklist
338
 */
339
interface PluginPublishingChecklist {
340
  packageJson: 'Complete package.json with correct metadata';
341
  readme: 'Comprehensive README with usage examples';
342
  types: 'TypeScript definition files for API';
343
  tests: 'Unit tests covering plugin functionality';
344
  examples: 'Example projects demonstrating plugin usage';
345
  license: 'Open source license file';
346
  changelog: 'Version history and changes';
347
}
348

349
/**
350
 * Recommended package.json structure for plugins
351
 */
352
interface PluginPackageJson {
353
  name: string;
354
  version: string;
355
  description: string;
356
  main: 'dist/index.js';
357
  types: 'dist/index.d.ts';
358
  keywords: ['taro', 'plugin', 'mini-program'];
359
  peerDependencies: {
360
    '@tarojs/cli': '^4.0.0';
361
  };
362
  files: ['dist', 'README.md'];
363
}
364
```