0
# Taro Service
1

2
Taro Service is the core service layer for the Taro cross-platform development framework. It provides a comprehensive plugin system with lifecycle hooks, configuration management with validation, and platform abstraction layers for different target environments (mini-programs, web, native apps).
3

4
## Package Information
5

6
- **Package Name**: @tarojs/service
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @tarojs/service`
10

11
## Core Imports
12

13
```typescript
14
import { Config, Kernel, TaroPlatform, TaroPlatformBase, TaroPlatformWeb } from "@tarojs/service";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { Config, Kernel, TaroPlatform, TaroPlatformBase, TaroPlatformWeb } = require("@tarojs/service");
21
```
22

23
Import types:
24

25
```typescript
26
import type { IPluginContext, IPaths, IPlugin, IHook, ICommand, IPlatform, TConfig } from "@tarojs/service";
27
```
28

29
## Basic Usage
30

31
```typescript
32
import { Kernel, Config } from "@tarojs/service";
33

34
// Initialize configuration
35
const config = new Config({ appPath: process.cwd() });
36
await config.init({ mode: 'development', command: 'build' });
37

38
// Create kernel instance
39
const kernel = new Kernel({
40
  appPath: process.cwd(),
41
  config,
42
  plugins: ['@tarojs/plugin-react']
43
});
44

45
// Run a command
46
await kernel.run({
47
  name: 'build',
48
  opts: { platform: 'weapp' }
49
});
50
```
51

52
## Architecture
53

54
Taro Service is built around several key components:
55

56
- **Kernel**: Central orchestrator managing plugins, commands, platforms, and the build process
57
- **Configuration Management**: Handles local and global Taro project configuration with validation
58
- **Plugin System**: Event-driven architecture with lifecycle hooks, method registration, and validation
59
- **Platform Abstraction**: Abstract base classes for different target platforms with transaction-based builds
60
- **Hook System**: Comprehensive lifecycle hooks for build customization (onBuildStart, modifyWebpackChain, etc.)
61

62
## Capabilities
63

64
### Configuration Management
65

66
Comprehensive configuration handling for Taro projects including local project config and global Taro settings.
67

68
```typescript { .api }
69
class Config {
70
  constructor(opts: IConfigOptions);
71
  init(configEnv: { mode: string; command: string }): Promise<void>;
72
  getConfigWithNamed(platform: string, configName: string): TConfig;
73
}
74

75
interface IConfigOptions {
76
  appPath: string;
77
  disableGlobalConfig?: boolean;
78
}
79
```
80

81
[Configuration Management](./configuration.md)
82

83
### Plugin System & Kernel
84

85
Core orchestration system managing plugins, commands, platforms, and the complete build process with event-driven architecture.
86

87
```typescript { .api }
88
class Kernel extends EventEmitter {
89
  constructor(options: IKernelOptions);
90
  run(args: string | { name: string; opts?: any }): Promise<void>;
91
  applyPlugins(args: string | { name: string; initialVal?: any; opts?: any }): Promise<any>;
92
}
93

94
interface IKernelOptions {
95
  appPath: string;
96
  config: Config;
97
  presets?: PluginItem[];
98
  plugins?: PluginItem[];
99
}
100
```
101

102
[Plugin System & Kernel](./plugin-system.md)
103

104
### Platform Abstraction
105

106
Abstract base classes for implementing custom platforms with transaction-based build processes and platform-specific configurations.
107

108
```typescript { .api }
109
abstract class TaroPlatform<T extends TConfig = TConfig> {
110
  constructor(ctx: IPluginContext, config: T);
111
  abstract start(): Promise<void>;
112
  getConfig(): T;
113
}
114

115
abstract class TaroPlatformBase<T extends TConfig = TConfig> extends TaroPlatform<T> {
116
  platformType: PLATFORM_TYPE.MINI;
117
  abstract globalObject: string;
118
  abstract fileType: IFileType;
119
  abstract template: RecursiveTemplate | UnRecursiveTemplate;
120
}
121

122
abstract class TaroPlatformWeb<T extends TConfig = TConfig> extends TaroPlatform<T> {
123
  platformType: PLATFORM_TYPE.WEB;
124
}
125
```
126

127
[Platform Abstraction](./platform-abstraction.md)
128

129
### Plugin Context API
130

131
Complete plugin development API providing access to the service layer's capabilities including lifecycle hooks, method registration, and build customization.
132

133
```typescript { .api }
134
interface IPluginContext {
135
  plugins: Map<string, IPlugin>;
136
  platforms: Map<string, IPlatform>;
137
  paths: IPaths;
138
  runOpts: any;
139
  helper: typeof helper;
140
  runnerUtils: typeof runnerUtils;
141
  initialConfig: IProjectConfig;
142
  
143
  // Registration methods
144
  register(hook: IHook): void;
145
  registerMethod(arg: string | { name: string; fn?: Func }, fn?: Func): void;
146
  registerCommand(command: ICommand): void;
147
  registerPlatform(platform: IPlatform): void;
148
  
149
  // Hook execution
150
  applyPlugins(args: string | { name: string; initialVal?: any; opts?: any }): Promise<any>;
151
}
152
```
153

154
[Plugin Context API](./plugin-context.md)
155

156
## Core Types
157

158
```typescript { .api }
159
interface IPaths {
160
  appPath: string;
161
  configPath: string;
162
  sourcePath: string;
163
  outputPath: string;
164
  nodeModulesPath: string;
165
}
166

167
interface IPlugin {
168
  id: string;
169
  path: string;
170
  opts: any;
171
  type: PluginType;
172
  apply: Func;
173
}
174

175
interface IHook {
176
  name: string;
177
  plugin?: string;
178
  fn: Func;
179
  before?: string;
180
  stage?: number;
181
}
182

183
interface ICommand extends IHook {
184
  alias?: string;
185
  optionsMap?: Record<string, string>;
186
  synopsisList?: string[];
187
}
188

189
interface IPlatform extends IHook {
190
  useConfigName?: string;
191
}
192

193
type TConfig = Record<string, any>;
194
type IPluginsObject = Record<string, Record<any, any> | null>;
195
```