0
# Configuration Management
1

2
Configuration management system for Taro projects providing local project configuration and global Taro settings with validation and environment support.
3

4
## Capabilities
5

6
### Config Class
7

8
Main configuration management class that handles both local project config and global Taro configuration.
9

10
```typescript { .api }
11
/**
12
 * Main configuration management class for Taro projects
13
 */
14
class Config {
15
  appPath: string;
16
  configPath: string;
17
  initialConfig: IProjectConfig;
18
  initialGlobalConfig: IProjectConfig;
19
  isInitSuccess: boolean;
20
  disableGlobalConfig: boolean;
21

22
  constructor(opts: IConfigOptions);
23
  init(configEnv: { mode: string; command: string }): Promise<void>;
24
  initGlobalConfig(command?: string): void;
25
  getConfigWithNamed(platform: string, configName: string): TConfig;
26
}
27

28
interface IConfigOptions {
29
  /** Current command execution directory, or project path for build commands */
30
  appPath: string;
31
  /** Whether to disable global configuration loading */
32
  disableGlobalConfig?: boolean;
33
}
34
```
35

36
**Usage Examples:**
37

38
```typescript
39
import { Config } from "@tarojs/service";
40

41
// Basic configuration setup
42
const config = new Config({ appPath: process.cwd() });
43
await config.init({ mode: 'development', command: 'build' });
44

45
console.log(config.isInitSuccess); // true if config loaded successfully
46
console.log(config.initialConfig); // Project configuration object
47

48
// Get platform-specific configuration
49
const weappConfig = config.getConfigWithNamed('weapp', 'mini');
50
```
51

52
### Configuration Initialization
53

54
Initialize configuration with environment-specific settings and command context.
55

56
```typescript { .api }
57
/**
58
 * Initialize configuration with environment and command context
59
 * @param configEnv - Environment configuration containing mode and command
60
 */
61
init(configEnv: { mode: string; command: string }): Promise<void>;
62
```
63

64
The `init` method:
65
- Loads project configuration from `config/index.(js|ts)` file
66
- Loads global Taro configuration from user home directory
67
- Supports function-based configuration that receives `merge` utility and environment
68
- Sets `isInitSuccess` to true if configuration loads successfully
69

70
### Global Configuration
71

72
Manage global Taro configuration stored in user's home directory.
73

74
```typescript { .api }
75
/**
76
 * Initialize global Taro configuration from user home directory
77
 * @param command - Optional command name to filter plugins
78
 */
79
initGlobalConfig(command?: string): void;
80
```
81

82
Global configuration features:
83
- Loaded from `~/.taro/config.json`
84
- Supports command-specific plugin filtering
85
- Gracefully handles missing or invalid global config files
86
- Provides visual feedback during loading process
87

88
### Platform Configuration
89

90
Generate platform-specific configuration by merging base config with platform overrides.
91

92
```typescript { .api }
93
/**
94
 * Get configuration for a specific platform with named config section
95
 * @param platform - Target platform name (e.g., 'weapp', 'h5')
96
 * @param configName - Configuration section name to merge
97
 * @returns Merged configuration object for the platform
98
 */
99
getConfigWithNamed(platform: string, configName: string): TConfig;
100
```
101

102
Returns a merged configuration containing:
103
- Entry point configuration with resolved file paths
104
- Platform-specific settings and overrides
105
- Build tool configuration (compiler, cache, etc.)
106
- Asset handling configuration (copy, alias, etc.)
107

108
**Usage Example:**
109

110
```typescript
111
// Get WeChat mini-program configuration
112
const weappConfig = config.getConfigWithNamed('weapp', 'mini');
113

114
// Get H5 configuration  
115
const h5Config = config.getConfigWithNamed('h5', 'h5');
116
```
117

118
## Configuration File Structure
119

120
The configuration file (`config/index.js` or `config/index.ts`) can export either an object or a function:
121

122
**Object Export:**
123
```typescript
124
export default {
125
  projectName: 'my-taro-app',
126
  sourceRoot: 'src',
127
  outputRoot: 'dist',
128
  framework: 'react',
129
  compiler: 'webpack5',
130
  plugins: ['@tarojs/plugin-react'],
131
  mini: {
132
    // Mini-program specific config
133
  },
134
  h5: {
135
    // H5 specific config
136
  }
137
};
138
```
139

140
**Function Export:**
141
```typescript
142
export default (merge, { command, mode }) => {
143
  const config = {
144
    projectName: 'my-taro-app',
145
    // ... base config
146
  };
147
  
148
  if (mode === 'development') {
149
    config.cache = { enable: true };
150
  }
151
  
152
  return config;
153
};
154
```
155

156
## Types
157

158
```typescript { .api }
159
interface IProjectConfig {
160
  projectName?: string;
161
  sourceRoot?: string;
162
  outputRoot?: string;
163
  framework?: string;
164
  compiler?: string | { type: string };
165
  plugins?: PluginItem[];
166
  presets?: PluginItem[];
167
  cache?: { enable: boolean };
168
  alias?: Record<string, string>;
169
  copy?: any;
170
  defineConstants?: Record<string, any>;
171
  env?: Record<string, any>;
172
  [platform: string]: any; // Platform-specific configurations
173
}
174

175
type PluginItem = string | [string, any];
176
```