Webpack Config Finder Utility

2.2.1 · maintenance · verified Sun Apr 19

find-webpack is a utility library designed to programmatically locate and modify Webpack configuration settings, particularly useful for projects built with `react-scripts` (Create React App) or custom Webpack setups. As of its latest stable version, 2.2.1 (released January 2021), it provides functions to extract Webpack options, including handling the nuances of `react-scripts`'s hidden configurations. It also offers specific utilities for integrating with tools like Cypress, enabling cleanup of optimization plugins and dynamic addition of folders to Babel's transpilation scope for testing purposes. While its release cadence has been irregular since 2021, it was actively maintained with features and bug fixes throughout 2020, differentiating itself by simplifying complex Webpack config access and modification for specific ecosystem integrations.

Common errors

```
TypeError: Cannot read property 'includes' of undefined
```
cause This error often occurs in versions before 2.2.1 when `cleanForCypress` is called with `addFolderToTranspile` and the internal Babel presets array is undefined.

fix Upgrade `find-webpack` to version `2.2.1` or later. Alternatively, ensure the Babel configuration passed to `cleanForCypress` explicitly defines presets if you're manipulating them.
```
Webpack config is undefined or null when calling getWebpackOptions()
```
cause When using `find-webpack` to detect a `react-scripts` configuration, it expects a `package.json` file to be present in the current working directory to properly initialize `react-scripts`'s environment.

fix Ensure that the script calling `getWebpackOptions()` is executed from the root directory of your project, where the `package.json` file resides.
```
Incorrect environment variables (NODE_ENV, BABEL_ENV) detected after loading webpack config
```
cause The `tryLoadingWebpackConfig` and `getWebpackOptions` functions in `find-webpack` may internally set `process.env.NODE_ENV` and `process.env.BABEL_ENV` to 'development' or 'test' (for v2.0.0+) during config loading, which can persist.

fix Be mindful of this side effect. If you need specific environment variables, set them before calling `find-webpack` functions or reset them immediately afterwards.

Warnings

breaking When loading webpack configurations, `find-webpack` version 2.0.0 introduced a breaking change that requires `process.env.NODE_ENV` to be set to 'test' for proper loading of environment variables and plugins, particularly for `react-scripts` based projects.
Fix: Ensure `process.env.NODE_ENV` is set to 'test' before calling `getWebpackOptions` or `tryLoadingWebpackConfig` if you encounter issues with environment-dependent config loading in `react-scripts`.
gotcha The `getWebpackOptions` function, when used with `react-scripts` projects, expects a `package.json` file to be present in the current working directory (`process.cwd()`). If `package.json` is missing, `react-scripts` will not load its configuration, and `find-webpack` will fail to retrieve it.
Fix: Run your script from the root of your project where `package.json` is located, or ensure your `process.cwd()` is correctly set if running from a non-standard environment.
gotcha The `tryLoadingWebpackConfig` function and implicitly `getWebpackOptions` can set `process.env.BABEL_ENV` and `process.env.NODE_ENV` to 'development' during the loading process and leave them in that state. This could unintentionally affect other parts of your application or build process that rely on these environment variables.
Fix: Be aware of these side effects. If precise control over `NODE_ENV` and `BABEL_ENV` is critical, consider resetting them after `find-webpack` operations or inspecting their values. For `v2.0.0+` specifically, `NODE_ENV` being 'test' is expected for some scenarios.
gotcha A bug in earlier versions (fixed in v2.2.1) could lead to a `TypeError: Cannot read property 'includes' of undefined` when using the `addFolderToTranspile` option within `cleanForCypress`, if `options.babelPresets` was undefined.
Fix: Upgrade to `find-webpack@2.2.1` or newer to resolve this bug. If unable to upgrade, ensure `options.babelPresets` is explicitly defined if you're dynamically modifying Babel configuration.

Install

npm install find-webpack npm
yarn add find-webpack yarn
pnpm add find-webpack pnpm

Imports

getWebpackOptions

wrong:

import findWebpack from 'find-webpack';
const config = findWebpack.getWebpackOptions();

correct:

import { getWebpackOptions } from 'find-webpack';
// Or for CJS:
const { getWebpackOptions } = require('find-webpack');

The library primarily uses named exports. Direct `require('find-webpack')` returns an object with all functions.

tryLoadingWebpackConfig

wrong:

const config = require('find-webpack').tryLoadingWebpackConfig();

correct:

import { tryLoadingWebpackConfig } from 'find-webpack';
// Or for CJS:
const { tryLoadingWebpackConfig } = require('find-webpack');

This function attempts to load a webpack.config.js file from a given path and may modify process.env.NODE_ENV and process.env.BABEL_ENV.

cleanForCypress
wrong:
```
findWebpack.cleanForCypress(opts, config);
```
correct:
```
import { cleanForCypress } from 'find-webpack';
// Or for CJS:
const { cleanForCypress } = require('find-webpack');
```
This function modifies the provided Webpack config object in place, typically for Cypress integration. It accepts an options object and the config to modify.

Quickstart

This quickstart demonstrates how to find an application's Webpack configuration (especially from react-scripts) and then modify it using `cleanForCypress` to prepare it for Cypress component testing, including adding coverage instrumentation and specifying additional folders for Babel transpilation.

import { getWebpackOptions, cleanForCypress } from 'find-webpack';
import path from 'path';

const projectRoot = process.cwd();

console.log('Attempting to find Webpack options...');
let webpackConfig = getWebpackOptions();

if (webpackConfig) {
  console.log('Webpack config found. Initial entry points:', webpackConfig.entry);

  // Example of cleaning the config for Cypress with coverage and custom folder transpilation
  const cypressComponentFolder = path.join(projectRoot, 'cypress', 'component');
  const cypressFixturesFolder = path.join(projectRoot, 'cypress', 'fixtures');

  const cleanOptions = {
    reactScripts: true, // Specific cleanup for react-scripts projects
    coverage: true,     // Add istanbul babel plugin for code coverage
    addFolderToTranspile: [cypressComponentFolder, cypressFixturesFolder],
    looseModules: true // Enable @babel/plugin-transform-modules-commonjs
  };

  cleanForCypress(cleanOptions, webpackConfig);
  console.log('Webpack config cleaned for Cypress. Modified entry points:', webpackConfig.entry);
  // console.log('Full modified config:', JSON.stringify(webpackConfig, null, 2));
} else {
  console.warn('Could not find Webpack options. Ensure package.json is in CWD or pass a config path.');
}

view raw JSON →