0
# Utilities and Helpers
1

2
Utility functions and path resolution helpers for accessing react-scripts internals and integrating with third-party tools.
3

4
## Capabilities
5

6
### Main Exports (Deprecated)
7

8
Legacy helper functions from the main entry point, deprecated as of v2.0.
9

10
```javascript { .api }
11
const { 
12
  getLoader,           // function - deprecated, throws error
13
  loaderNameMatches,   // function - deprecated, throws error  
14
  getBabelLoader,      // function - deprecated, throws error
15
  injectBabelPlugin,   // function - deprecated, throws error
16
  compose,             // function - deprecated, throws error
17
  paths                // object - current paths configuration
18
} = require('react-app-rewired');
19
```
20

21
**Usage Example:**
22

23
```javascript
24
const { paths } = require('react-app-rewired');
25

26
// Access paths for third-party integration
27
console.log(paths.appSrc);        // Source directory path
28
console.log(paths.appBuild);      // Build directory path
29
console.log(paths.scriptVersion); // react-scripts module path
30
```
31

32
**Deprecation Note:** All helper functions except `paths` are deprecated and will throw errors directing users to [customize-cra](https://github.com/arackaf/customize-cra).
33

34
### Paths Utilities
35

36
Path resolution and configuration utilities from the paths module.
37

38
```javascript { .api }
39
/**
40
 * Extended paths object with react-app-rewired specific properties
41
 */
42
const paths = require('react-app-rewired/scripts/utils/paths');
43

44
interface PathsObject {
45
  // react-scripts paths (inherited via Object.assign)
46
  appPath: string;              // Project root directory
47
  appSrc: string;               // Source directory  
48
  appBuild: string;             // Build output directory
49
  appPublic: string;            // Public assets directory
50
  appPackageJson: string;       // package.json file path
51
  appIndexJs: string;           // Main index.js file
52
  appHtml: string;              // HTML template file
53
  
54
  // react-app-rewired specific paths (from paths.js)
55
  scriptVersion: string;        // Path to react-scripts module directory
56
  configOverrides: string;      // Path to config-overrides file/directory
57
  customScriptsIndex: number;   // Index of --scripts-version arg (-1 if not present)
58
  configOverridesIndex: number; // Index of --config-overrides arg (-1 if not present)
59
  
60
  // All other paths from react-scripts/config/paths are also available
61
  // via Object.assign({}, paths, overrides.paths(pathsConfig, process.env.NODE_ENV))
62
}
63
```
64

65
**Usage Examples:**
66

67
```javascript
68
const paths = require('react-app-rewired/scripts/utils/paths');
69

70
// Access react-scripts module directory
71
const webpackConfig = require(`${paths.scriptVersion}/config/webpack.config`);
72

73
// Check if custom scripts version was specified
74
if (paths.customScriptsIndex > -1) {
75
  console.log('Using custom react-scripts version');
76
}
77

78
// Access config overrides path
79
const overrides = require(paths.configOverrides);
80
```
81

82
### Dependency Resolution Utilities
83

84
Utilities for requiring modules relative to the react-scripts installation.
85

86
```javascript { .api }
87
/**
88
 * Dependency resolution utilities
89
 */
90
const { dependRequire, dependRequireResolve } = require('react-app-rewired/scripts/utils/dependRequire');
91

92
/**
93
 * Resolve module path relative to react-scripts
94
 * @param id - Module identifier to resolve
95
 * @returns Resolved module path
96
 */
97
function dependRequireResolve(id: string): string;
98

99
/**
100
 * Require module relative to react-scripts  
101
 * @param id - Module identifier to require
102
 * @returns Required module
103
 */
104
function dependRequire(id: string): any;
105
```
106

107
**Usage Examples:**
108

109
```javascript
110
const { dependRequire, dependRequireResolve } = require('react-app-rewired/scripts/utils/dependRequire');
111

112
// Require babel-jest from react-scripts context
113
const babelJest = dependRequire('babel-jest');
114

115
// Resolve path to babel preset
116
const presetPath = dependRequireResolve('babel-preset-react-app');
117

118
// Use in webpack config
119
config.module.rules.push({
120
  test: /\.js$/,
121
  use: {
122
    loader: dependRequireResolve('babel-loader'),
123
    options: {
124
      presets: [dependRequireResolve('babel-preset-react-app')]
125
    }
126
  }
127
});
128
```
129

130
### Jest Configuration Utilities
131

132
Utilities for customizing Jest configuration with package.json overrides.
133

134
```javascript { .api }
135
/**
136
 * Jest configuration merge utility
137
 * @param config - Base Jest configuration from react-scripts
138
 * @returns Merged Jest configuration with package.json overrides
139
 */
140
const rewireJestConfig = require('react-app-rewired/scripts/utils/rewireJestConfig');
141

142
function rewireJestConfig(config: any): any;
143
```
144

145
**Usage Examples:**
146

147
```javascript
148
const rewireJestConfig = require('react-app-rewired/scripts/utils/rewireJestConfig');
149

150
// In jest override function
151
jest: function(config) {
152
  // Apply package.json jest overrides first
153
  config = rewireJestConfig(config);
154
  
155
  // Then apply additional customizations
156
  config.testTimeout = 10000;
157
  
158
  return config;
159
}
160
```
161

162
**Merge Behavior:**
163
- String, number, boolean values: Overwrite completely
164
- Arrays: Concatenate package.json values with default values  
165
- Objects: Merge properties, with package.json taking precedence
166

167
### Babel Transform Utilities  
168

169
Custom Babel transformer module for Jest with JSX runtime detection.
170

171
```javascript { .api }
172
/**
173
 * Custom babel-jest transformer module with react-app preset
174
 * This is a pre-configured transformer, not a function
175
 */
176
const babelTransform = require('react-app-rewired/scripts/utils/babelTransform');
177

178
// The module exports a babel-jest transformer with this configuration:
179
interface BabelTransformerConfig {
180
  presets: [
181
    [string, { runtime: 'automatic' | 'classic' }]
182
  ];
183
  plugins: any[];
184
  babelrc: true;  // Allows .babelrc files to be respected
185
}
186
```
187

188
**Implementation Details from babelTransform.js:**
189
```javascript { .api }
190
// JSX runtime detection logic
191
const hasJsxRuntime = (() => {
192
  if (process.env.DISABLE_NEW_JSX_TRANSFORM === 'true') {
193
    return false;
194
  }
195
  try {
196
    require.resolve('react/jsx-runtime');
197
    return true;
198
  } catch (e) {
199
    return false;
200
  }
201
})();
202

203
// Creates transformer with:
204
// runtime: hasJsxRuntime ? 'automatic' : 'classic'
205
// babelrc: true
206
```
207

208
**Features:**
209
- Automatic JSX runtime detection (React 17+)
210
- Falls back to classic JSX transform if `react/jsx-runtime` not available
211
- Respects `DISABLE_NEW_JSX_TRANSFORM=true` environment variable
212
- Uses `babel-preset-react-app` with appropriate runtime configuration
213
- Honors `.babelrc` files in the project
214

215
### Third-Party Integration
216

217
Utilities for integrating react-app-rewired with external tools.
218

219
```javascript { .api }
220
/**
221
 * Export rewired webpack config for third-party tools
222
 * Create webpack.config.js in project root:
223
 */
224
const { paths } = require('react-app-rewired');
225
const overrides = require('react-app-rewired/config-overrides');
226
const config = require(paths.scriptVersion + '/config/webpack.config.dev');
227

228
module.exports = overrides.webpack(config, process.env.NODE_ENV);
229
```
230

231
**Supported Tools:**
232
- [react-cosmos](https://github.com/react-cosmos/react-cosmos)
233
- webpack-bundle-analyzer
234
- Storybook
235
- Any tool that accepts a webpack configuration file
236

237
### Environment Detection
238

239
```javascript { .api }
240
// Environment variables used by utilities
241
process.env.NODE_ENV                    // 'development', 'production', 'test'
242
process.env.REACT_SCRIPTS_VERSION      // Custom react-scripts package name
243
process.env.DISABLE_NEW_JSX_TRANSFORM  // 'true' to disable automatic JSX runtime
244
```
245

246
### File System Utilities
247

248
```javascript { .api }
249
// Custom config-overrides path detection
250
const projectDir = require('fs').realpathSync(process.cwd());
251
const packageJson = require(path.resolve(projectDir, 'package.json'));
252
const customPath = packageJson['config-overrides-path'];
253

254
// Resolves to:
255
// 1. Custom path from package.json 'config-overrides-path'
256
// 2. Command line --config-overrides argument  
257
// 3. Default: ./config-overrides (file or directory)
258
```