0
# Configuration
1

2
Configuration loading and management system for SVGO settings, supporting automatic config file discovery and custom configuration options.
3

4
## Capabilities
5

6
### Load Configuration
7

8
Load SVGO configuration from files or search for config files automatically.
9

10
```javascript { .api }
11
/**
12
 * Load SVGO configuration from a file or search for config files
13
 * @param configFile - Optional path to config file (absolute or relative)
14
 * @param cwd - Optional current working directory for relative paths and search
15
 * @returns Promise resolving to configuration object or null if not found
16
 */
17
function loadConfig(configFile?: string, cwd?: string): Promise<Config | null>;
18

19
interface Config {
20
  path?: string;
21
  multipass?: boolean;
22
  floatPrecision?: number;
23
  plugins?: PluginConfig[];
24
  js2svg?: StringifyOptions;
25
  datauri?: DataUri;
26
}
27
```
28

29
**Usage Examples:**
30

31
```javascript
32
import { loadConfig } from "svgo";
33

34
// Load specific config file
35
const config = await loadConfig('./my-svgo-config.js');
36

37
// Load config with custom working directory
38
const config = await loadConfig('svgo.config.js', '/path/to/project');
39

40
// Auto-search for config files in current directory and parents
41
const config = await loadConfig();
42

43
// Use loaded config with optimize
44
import { optimize } from "svgo";
45
const result = optimize(svgString, config);
46
```
47

48
### Configuration File Discovery
49

50
When no config file is specified, `loadConfig()` searches for configuration files in the following order:
51

52
1. `svgo.config.js` in current directory
53
2. `svgo.config.mjs` in current directory  
54
3. `svgo.config.cjs` in current directory
55
4. Repeat search in parent directories up to filesystem root
56

57
**Supported Config File Formats:**
58

59
```javascript
60
// svgo.config.js (ES Module)
61
export default {
62
  multipass: true,
63
  plugins: [
64
    'preset-default',
65
    {
66
      name: 'removeAttrs',
67
      params: {
68
        attrs: ['data-*']
69
      }
70
    }
71
  ]
72
};
73

74
// svgo.config.cjs (CommonJS)
75
module.exports = {
76
  floatPrecision: 2,
77
  plugins: ['preset-default']
78
};
79

80
// svgo.config.mjs (ES Module)
81
export default {
82
  js2svg: {
83
    pretty: true,
84
    indent: 2
85
  }
86
};
87
```
88

89
### Configuration Validation
90

91
Configuration files must export a valid configuration object.
92

93
```javascript { .api }
94
// Valid configuration object structure
95
interface Config {
96
  /** File path context for plugins */
97
  path?: string;
98
  /** Enable multiple optimization passes */
99
  multipass?: boolean;
100
  /** Floating point precision for numeric values */
101
  floatPrecision?: number;
102
  /** Plugin configuration array */
103
  plugins?: PluginConfig[];
104
  /** SVG output formatting options */
105
  js2svg?: StringifyOptions;
106
  /** Data URI output format */
107
  datauri?: DataUri;
108
}
109
```
110

111
**Configuration Examples:**
112

113
```javascript
114
// Basic configuration
115
{
116
  plugins: ['preset-default']
117
}
118

119
// Advanced configuration
120
{
121
  multipass: true,
122
  floatPrecision: 2,
123
  plugins: [
124
    {
125
      name: 'preset-default',
126
      params: {
127
        overrides: {
128
          removeViewBox: false,
129
          cleanupIds: {
130
            preserve: ['important-id']
131
          }
132
        }
133
      }
134
    },
135
    'removeDimensions',
136
    {
137
      name: 'addClassesToSVGElement',
138
      params: {
139
        classNames: ['optimized-svg']
140
      }
141
    }
142
  ],
143
  js2svg: {
144
    pretty: true,
145
    indent: 2,
146
    finalNewline: true
147
  }
148
}
149
```
150

151
### Plugin Configuration Types
152

153
Different ways to configure plugins in the configuration file.
154

155
```javascript { .api }
156
type PluginConfig = 
157
  | string  // Plugin name with default parameters
158
  | {
159
      name: string;
160
      params?: any;
161
      fn?: Plugin;  // Custom plugin function
162
    }
163
  | CustomPlugin;
164

165
interface CustomPlugin<T = any> {
166
  name: string;
167
  fn: Plugin<T>;
168
  params?: T;
169
}
170
```
171

172
**Plugin Configuration Examples:**
173

174
```javascript
175
// String format (default parameters)
176
{
177
  plugins: [
178
    'removeComments',
179
    'cleanupAttrs',
180
    'preset-default'
181
  ]
182
}
183

184
// Object format with parameters
185
{
186
  plugins: [
187
    {
188
      name: 'convertColors',
189
      params: {
190
        currentColor: true,
191
        names2hex: false,
192
        rgb2hex: true,
193
        shorthex: true,
194
        shortname: true
195
      }
196
    }
197
  ]
198
}
199

200
// Custom plugin
201
{
202
  plugins: [
203
    {
204
      name: 'customPlugin',
205
      fn: (root, params, info) => {
206
        return {
207
          element: {
208
            enter(node) {
209
              // Custom optimization logic
210
            }
211
          }
212
        };
213
      },
214
      params: {
215
        customParam: 'value'
216
      }
217
    }
218
  ]
219
}
220
```
221

222
### Preset Configuration
223

224
Configure the default preset with custom overrides.
225

226
```javascript { .api }
227
interface PresetDefaultConfig {
228
  /** Floating point precision override */
229
  floatPrecision?: number;
230
  /** Override individual plugin settings */
231
  overrides?: {
232
    [pluginName: string]: any | false;  // false disables the plugin
233
  };
234
}
235
```
236

237
**Preset Override Examples:**
238

239
```javascript
240
// Disable specific plugins in preset-default
241
{
242
  plugins: [
243
    {
244
      name: 'preset-default',
245
      params: {
246
        overrides: {
247
          removeViewBox: false,  // Keep viewBox
248
          removeDesc: false,     // Keep description elements
249
          cleanupIds: false      // Don't optimize IDs
250
        }
251
      }
252
    }
253
  ]
254
}
255

256
// Customize plugin parameters within preset
257
{
258
  plugins: [
259
    {
260
      name: 'preset-default',
261
      params: {
262
        overrides: {
263
          convertColors: {
264
            currentColor: true,
265
            names2hex: false
266
          },
267
          cleanupNumericValues: {
268
            floatPrecision: 3
269
          }
270
        }
271
      }
272
    }
273
  ]
274
}
275
```
276

277
### Environment-Specific Configuration
278

279
Configuration can vary based on the environment or use case.
280

281
```javascript
282
// svgo.config.js
283
const isProduction = process.env.NODE_ENV === 'production';
284

285
export default {
286
  multipass: isProduction,  // Only multipass in production
287
  plugins: [
288
    {
289
      name: 'preset-default',
290
      params: {
291
        overrides: {
292
          // Keep IDs in development for debugging
293
          cleanupIds: isProduction,
294
          // Pretty print in development
295
          ...(isProduction ? {} : { pretty: true })
296
        }
297
      }
298
    }
299
  ],
300
  js2svg: {
301
    pretty: !isProduction,
302
    indent: isProduction ? 0 : 2
303
  }
304
};
305
```
306

307
### Configuration Errors
308

309
Common configuration errors and how to handle them.
310

311
```javascript
312
import { loadConfig } from "svgo";
313

314
try {
315
  const config = await loadConfig('./invalid-config.js');
316
} catch (error) {
317
  if (error.message.includes('Invalid config file')) {
318
    console.error('Config file must export an object');
319
  } else if (error.message.includes('Module not found')) {
320
    console.error('Config file not found');
321
  } else {
322
    console.error('Config loading failed:', error.message);
323
  }
324
}
325

326
// Config validation happens during optimize() call
327
import { optimize } from "svgo";
328

329
try {
330
  const result = optimize(svgString, {
331
    plugins: null  // Invalid: must be array
332
  });
333
} catch (error) {
334
  console.error('Invalid configuration:', error.message);
335
}
336
```