Configuration Guide

The core of react-app-rewired is the config-overrides.js file located in your project's root directory. This file is where you define all your configuration customizations.

Basic Configuration

By default, react-app-rewired looks for a config-overrides.js file that exports a single function. This function receives the webpack configuration object and the current environment ('development' or 'production') as arguments.

/* config-overrides.js */
module.exports = function override(config, env) {
  // Add a new plugin
  config.plugins.push(new MyWebpackPlugin());

  // Modify an existing rule
  // For more complex modifications, consider using a library like customize-cra

  return config;
}

Extended Configuration

For more advanced use cases, you can export an object from config-overrides.js instead of a single function. This allows you to customize the configurations for webpack, Jest, the webpack-dev-server, and CRA's internal paths.

The exported object can contain up to four functions:

• webpack: Customizes the webpack config for development and production builds.
• jest: Customizes the Jest config for tests.
• devServer: Customizes the webpack-dev-server config used by npm start.
• paths: Overrides the default paths used by react-scripts (e.g., appSrc, appBuild).

Example Extended Configuration

This example demonstrates how to use each of the override functions.

// config-overrides.js
const fs = require('fs');

module.exports = {
  // The Webpack config to use when compiling your react app for development or production.
  webpack: function(config, env) {
    // ...add your webpack config
    return config;
  },

  // The Jest config to use when running your jest tests.
  jest: function(config) {
    // ...add your jest config customisation...
    // Example: enable/disable some tests based on environment variables.
    if (!config.testPathIgnorePatterns) {
      config.testPathIgnorePatterns = [];
    }
    if (!process.env.RUN_COMPONENT_TESTS) {
      config.testPathIgnorePatterns.push('<rootDir>/src/components/**/*.test.js');
    }
    if (!process.env.RUN_REDUCER_TESTS) {
      config.testPathIgnorePatterns.push('<rootDir>/src/reducers/**/*.test.js');
    }
    return config;
  },

  // The function to use to create a webpack dev server configuration.
  devServer: function(configFunction) {
    // Return the replacement function for create-react-app to use.
    return function(proxy, allowedHost) {
      // Create the default config by calling configFunction with the proxy/allowedHost parameters
      const config = configFunction(proxy, allowedHost);

      // Example: set the dev server to use a specific certificate in https.
      config.https = {
        key: fs.readFileSync(process.env.REACT_HTTPS_KEY, 'utf8'),
        cert: fs.readFileSync(process.env.REACT_HTTPS_CERT, 'utf8'),
        ca: fs.readFileSync(process.env.REACT_HTTPS_CA, 'utf8'),
        passphrase: process.env.REACT_HTTPS_PASS
      };

      // Return your customised Webpack Development Server config.
      return config;
    };
  },

  // The paths config to use when compiling your react app for development or production.
  paths: function(paths, env) {
    // ...add your paths config
    return paths;
  },
}

Overriding Webpack (webpack)

This function behaves identically to the basic, single-function export. It receives the webpack config and env and must return the modified config. This is where most customizations, like adding plugins or loaders, will occur.

Overriding Jest (jest)

Because create-react-app runs tests directly through Jest without using webpack, any changes in your webpack override function will not apply to your tests. The jest function allows you to modify the Jest configuration object directly.

• Parameter: config (the default Jest configuration object).
• Return Value: The modified Jest configuration object.

Note that react-app-rewired also merges any configuration from a jest key in your package.json file. The jest function in config-overrides.js is for programmatic changes that are not possible with static JSON.

Overriding Dev Server (devServer)

The webpack development server has its own configuration, which is generated by a function within react-scripts. To override it, you must provide a new function that react-scripts can call.

• Parameter: configFunction (the original function from react-scripts that creates the dev server config).
• Return Value: A new function that accepts proxy and allowedHost and returns a complete webpack-dev-server configuration object. The easiest way to do this is to call the original configFunction inside your new function to get the default config, modify it, and then return it, as shown in the example above.

Overriding Paths (paths)

This function allows you to change the default paths that create-react-app uses for source files, build output, public assets, etc.

• Parameters: paths (the default paths object), env (the current environment).
• Return Value: The modified paths object.