0
# Configuration Overrides
1

2
Core system for customizing webpack, Jest, dev server, and paths configurations through override functions in `config-overrides.js`.
3

4
## Capabilities
5

6
### Single Function Override
7

8
Simple webpack-only configuration override using a single function export.
9

10
```javascript { .api }
11
/**
12
 * Single function export for webpack-only overrides
13
 * @param config - Webpack configuration object
14
 * @param env - Environment string ('development' or 'production')
15
 * @returns Modified webpack configuration
16
 */
17
module.exports = function override(config, env) {
18
  // Modify webpack config
19
  return config;
20
};
21
```
22

23
**Usage Example:**
24

25
```javascript
26
module.exports = function override(config, env) {
27
  // Add a new webpack plugin
28
  config.plugins.push(new SomeWebpackPlugin());
29
  
30
  // Modify existing rules
31
  const babelLoader = config.module.rules.find(rule => 
32
    rule.use && rule.use.find(use => use.loader && use.loader.includes('babel-loader'))
33
  );
34
  
35
  return config;
36
};
37
```
38

39
### Object-Based Overrides
40

41
Advanced configuration override using object export with separate functions for different aspects.
42

43
```javascript { .api }
44
/**
45
 * Object export with multiple override functions
46
 */
47
module.exports = {
48
  webpack: function(config, env) { return config; },
49
  jest: function(config) { return config; },
50
  devServer: function(configFunction) { return configFunction; },
51
  paths: function(paths, env) { return paths; }
52
};
53
```
54

55
### Webpack Override
56

57
Customize webpack configuration for development and production builds.
58

59
```javascript { .api }
60
/**
61
 * Webpack configuration override function
62
 * @param config - Webpack configuration object from react-scripts
63
 * @param env - Environment string ('development' or 'production')
64
 * @returns Modified webpack configuration object
65
 */
66
webpack: function(config, env) {
67
  // Modify webpack configuration
68
  return config;
69
}
70
```
71

72
**Usage Examples:**
73

74
```javascript
75
webpack: function(config, env) {
76
  // Add custom alias
77
  config.resolve.alias = {
78
    ...config.resolve.alias,
79
    '@': path.resolve(__dirname, 'src')
80
  };
81

82
  // Add custom loader
83
  config.module.rules.push({
84
    test: /\.custom$/,
85
    use: 'custom-loader'
86
  });
87

88
  // Modify existing rules
89
  const oneOfRule = config.module.rules.find(rule => rule.oneOf);
90
  oneOfRule.oneOf.unshift({
91
    test: /\.module\.scss$/,
92
    use: ['style-loader', 'css-loader', 'sass-loader']
93
  });
94

95
  return config;
96
}
97
```
98

99
### Jest Override
100

101
Customize Jest testing configuration beyond what's possible in package.json.
102

103
```javascript { .api }
104
/**
105
 * Jest configuration override function
106
 * @param config - Jest configuration object from react-scripts
107
 * @returns Modified Jest configuration object
108
 */
109
jest: function(config) {
110
  // Modify Jest configuration
111
  return config;
112
}
113
```
114

115
**Usage Examples:**
116

117
```javascript
118
jest: function(config) {
119
  // Add custom test path ignore patterns
120
  if (!config.testPathIgnorePatterns) {
121
    config.testPathIgnorePatterns = [];
122
  }
123
  
124
  if (!process.env.RUN_COMPONENT_TESTS) {
125
    config.testPathIgnorePatterns.push('<rootDir>/src/components/**/*.test.js');
126
  }
127

128
  // Add custom setup files
129
  config.setupFilesAfterEnv = config.setupFilesAfterEnv || [];
130
  config.setupFilesAfterEnv.push('<rootDir>/src/setupTests.js');
131

132
  // Modify module name mapping
133
  config.moduleNameMapper = {
134
    ...config.moduleNameMapper,
135
    '^@/(.*)$': '<rootDir>/src/$1'
136
  };
137

138
  return config;
139
}
140
```
141

142
### Dev Server Override
143

144
Customize webpack development server configuration.
145

146
```javascript { .api }
147
/**
148
 * Dev server configuration override function
149
 * @param configFunction - Original function that creates dev server config
150
 * @param env - Environment string (passed by react-app-rewired)
151
 * @returns New function that creates modified dev server config
152
 */
153
devServer: function(configFunction, env) {
154
  return function(proxy, allowedHost) {
155
    const config = configFunction(proxy, allowedHost);
156
    // Modify dev server config
157
    return config;
158
  };
159
}
160
```
161

162
**Usage Examples:**
163

164
```javascript
165
devServer: function(configFunction) {
166
  return function(proxy, allowedHost) {
167
    const config = configFunction(proxy, allowedHost);
168
    
169
    // Enable HTTPS with custom certificates
170
    const fs = require('fs');
171
    config.https = {
172
      key: fs.readFileSync(process.env.REACT_HTTPS_KEY, 'utf8'),
173
      cert: fs.readFileSync(process.env.REACT_HTTPS_CERT, 'utf8'),
174
      ca: fs.readFileSync(process.env.REACT_HTTPS_CA, 'utf8'),
175
      passphrase: process.env.REACT_HTTPS_PASS
176
    };
177

178
    // Add custom middleware
179
    config.before = function(app) {
180
      app.get('/api/health', (req, res) => {
181
        res.json({ status: 'ok' });
182
      });
183
    };
184

185
    return config;
186
  };
187
}
188
```
189

190
### Paths Override
191

192
Customize file paths used by react-scripts.
193

194
```javascript { .api }
195
/**
196
 * Paths configuration override function
197
 * @param paths - Paths object from react-scripts
198
 * @param env - Environment string ('development', 'production', or 'test')
199
 * @returns Modified paths object
200
 */
201
paths: function(paths, env) {
202
  // Modify paths configuration
203
  return paths;
204
}
205
```
206

207
**Usage Examples:**
208

209
```javascript
210
paths: function(paths, env) {
211
  // Change build directory
212
  paths.appBuild = path.resolve(__dirname, 'dist');
213
  
214
  // Add custom paths
215
  paths.appCustom = path.resolve(__dirname, 'custom');
216
  
217
  // Modify source directory (advanced use case)
218
  if (env === 'development') {
219
    paths.appSrc = path.resolve(__dirname, 'dev-src');
220
  }
221
  
222
  return paths;
223
}
224
```
225

226
### Configuration File Patterns
227

228
Different ways to organize your config-overrides.js file:
229

230
```javascript { .api }
231
// 1. Single file in project root
232
// config-overrides.js
233

234
// 2. Directory with index.js
235
// config-overrides/index.js
236

237
// 3. Custom path via package.json
238
{
239
  "config-overrides-path": "node_modules/some-preconfigured-rewire"
240
}
241

242
// 4. Custom path via command line
243
// --config-overrides ./custom/path/overrides.js
244
```
245

246
### Deprecation Warnings
247

248
React-app-rewired will automatically detect and warn about deprecated configuration patterns:
249

250
```javascript { .api }
251
// Deprecated dev server field (shows warning from config-overrides.js)
252
module.exports = {
253
  devserver: function(configFunction) { /* deprecated */ }
254
};
255

256
// Warning message displayed:
257
console.log(
258
  'Warning: `devserver` has been deprecated. Please use `devServer` instead as ' +
259
  '`devserver` will not be used in the next major release.'
260
);
261

262
// Modern dev server field
263
module.exports = {
264
  devServer: function(configFunction, env) { /* use this */ }
265
};
266
```
267

268
**Compatibility Note:** The system supports both `devServer` and `devserver` for backwards compatibility, but `devserver` shows a deprecation warning and will be removed in a future major release.