{"id":11685,"library":"react-dev-utils","title":"Create React App Development Utilities","description":"react-dev-utils is a collection of internal utility modules primarily used by Create React App (CRA) to abstract and manage webpack configurations, development server setups, build processes, and other development-related tasks. It includes tools for error formatting, path resolution, webpack plugin management like `ModuleScopePlugin`, and environment variable handling. The package is not typically consumed directly by applications but rather by build tools like `react-scripts`. Its versioning and release cadence are tightly coupled with `react-scripts`, making direct maintenance releases uncommon outside of major `react-scripts` updates. The current stable version of `react-dev-utils` is 12.0.1, which corresponds to `react-scripts` v5.x.x. This version incorporates significant updates such as webpack 5, Jest 27, and ESLint 8, ensuring compatibility with modern JavaScript ecosystems. It provides a standardized and optimized development experience for CRA projects, significantly minimizing configuration overhead for developers by encapsulating complex build logic. Developers typically interact with these utilities indirectly through `react-scripts` commands, though advanced users might import specific modules for custom setups, especially in ejected CRA applications.","status":"maintenance","version":"12.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/facebook/create-react-app","tags":["javascript"],"install":[{"cmd":"npm install react-dev-utils","lang":"bash","label":"npm"},{"cmd":"yarn add react-dev-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-dev-utils","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Most utilities are exported from specific subpaths within 'react-dev-utils', not directly from the main package entry. This plugin is crucial for preventing imports outside the 'src' directory in Create React App projects.","wrong":"import { ModuleScopePlugin } from 'react-dev-utils';\nconst ModuleScopePlugin = require('react-dev-utils/ModuleScopePlugin'); // CommonJS is also supported but ESM is preferred in modern setups.","symbol":"ModuleScopePlugin","correct":"import ModuleScopePlugin from 'react-dev-utils/ModuleScopePlugin';"},{"note":"This function is part of the `WebpackDevServerUtils` module and helps generate a webpack-dev-server configuration object following Create React App's conventions.","wrong":"import createDevServerConfig from 'react-dev-utils/WebpackDevServerUtils';\nconst createDevServerConfig = require('react-dev-utils/WebpackDevServerUtils').createDevServerConfig;","symbol":"createDevServerConfig","correct":"import { createDevServerConfig } from 'react-dev-utils/WebpackDevServerUtils';"},{"note":"This utility is a default export from its specific module and is used to format webpack compilation messages for improved readability in the console.","wrong":"import { formatWebpackMessages } from 'react-dev-utils/formatWebpackMessages';\nconst formatWebpackMessages = require('react-dev-utils/formatWebpackMessages');","symbol":"formatWebpackMessages","correct":"import formatWebpackMessages from 'react-dev-utils/formatWebpackMessages';"}],"quickstart":{"code":"import WebpackDevServer from 'webpack-dev-server';\nimport webpack from 'webpack';\nimport { createDevServerConfig, choosePort, prepareUrls } from 'react-dev-utils/WebpackDevServerUtils';\nimport openBrowser from 'react-dev-utils/openBrowser';\n\nasync function startCustomDevServer() {\n  const DEFAULT_PORT = parseInt(process.env.PORT || '3000', 10);\n  const HOST = process.env.HOST || '0.0.0.0';\n\n  const port = await choosePort(HOST, DEFAULT_PORT);\n  if (!port) {\n    console.log('No port found, exiting.');\n    return; \n  }\n\n  const protocol = process.env.HTTPS === 'true' ? 'https' : 'http';\n  const appName = 'My Custom React App';\n  const urls = prepareUrls(protocol, HOST, port, '/');\n\n  // Basic webpack configuration example\n  const webpackConfig: webpack.Configuration = {\n    mode: 'development',\n    entry: './src/index.tsx', // Assume a TypeScript entry point\n    output: {\n      path: process.cwd() + '/build',\n      filename: 'bundle.js',\n      publicPath: '/',\n    },\n    resolve: { extensions: ['.ts', '.tsx', '.js', '.jsx'] },\n    module: {\n      rules: [\n        { test: /\\.(ts|tsx)$/, loader: 'ts-loader', exclude: /node_modules/ },\n        { test: /\\.(js|jsx)$/, loader: 'babel-loader', exclude: /node_modules/ }\n      ],\n    },\n    plugins: [] // Add webpack plugins here\n  };\n\n  const devServerConfig = createDevServerConfig(\n    {\n      proxy: undefined,\n      allowedHost: undefined,\n      publicPath: webpackConfig.output?.publicPath,\n      contentBase: webpackConfig.output?.path,\n    },\n    urls.lanUrlForConfig\n  );\n\n  const compiler = webpack(webpackConfig);\n  const server = new WebpackDevServer(devServerConfig, compiler);\n\n  server.startCallback(() => {\n    console.log(`Starting the development server on ${urls.localUrlForBrowser}`);\n    openBrowser(urls.localUrlForBrowser!);\n  });\n\n  ['SIGINT', 'SIGTERM'].forEach(function (sig) {\n    process.on(sig, function () {\n      server.close();\n      process.exit();\n    });\n  });\n}\n\nstartCustomDevServer();\n","lang":"typescript","description":"Demonstrates how to set up a custom webpack development server using `react-dev-utils` for port selection, URL preparation, and dev server configuration, mimicking Create React App's internal logic. This example uses `webpack`, `webpack-dev-server`, and several utilities from `react-dev-utils` to initialize and manage the server."},"warnings":[{"fix":"For ejected projects, carefully review release notes for webpack, Jest, ESLint, and PostCSS. Manually update webpack configurations, Jest setups, ESLint rules, and PostCSS plugins to be compatible with their new major versions. Refer to the `react-scripts` v5 migration guide for common patterns.","message":"When `react-scripts` updated to v5.0.0, it introduced significant upgrades to underlying dependencies including webpack 5, Jest 27, ESLint 8, and PostCSS 8. Projects that have been ejected from Create React App or directly consume `react-dev-utils` will need to manually update their configurations and resolve potential breaking changes with these major dependency bumps.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Ensure your project's `tsconfig.json` is configured for TypeScript 4 if using TypeScript. For React 17, the new JSX transform might require no changes or minor adjustments depending on your Babel configuration, but be aware of its implications for global React import requirements.","message":"The `react-scripts` v4.0.0 release brought support for React 17, including the new JSX transform, and TypeScript 4. These changes can affect how JSX is transpiled and how TypeScript projects are configured.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"If directly consuming `react-dev-utils`, be prepared for potential undocumented breaking changes. Consider carefully whether directly importing is necessary, or if extending `react-scripts` (e.g., via tools like `craco`) is a more stable approach.","message":"`react-dev-utils` is primarily an internal package for Create React App (`react-scripts`). While its modules are exported and can be used directly, its API is not officially stable and may introduce breaking changes without explicit major version bumps or extensive documentation, as its main consumer is `react-scripts`.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Always ensure your `react-scripts` package (and by extension, `react-dev-utils` if used directly) is updated to the latest stable patch version to mitigate any reported security vulnerabilities, even if they are described as non-impacting for CRA projects.","message":"Several `react-scripts` patch releases (e.g., v3.4.2, v3.4.3, v3.4.4) addressed `npm audit` warnings related to transitive dependencies like `webpack-dev-server`, `terser-webpack-plugin`, and `resolve-url-loader`. While these vulnerabilities were often deemed not to directly affect Create React App projects, they could trigger security scanner warnings.","severity":"gotcha","affected_versions":">=3.4.2 <4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure all your application code and components are located within the `src` directory or any other directories explicitly configured to be within the module scope. If you genuinely need to import from outside, you might need to eject and modify the webpack configuration, or use tools like `craco` to override the `ModuleScopePlugin`.","cause":"This error often occurs when `ModuleScopePlugin` prevents imports from outside the `src` folder (or other configured root directories) in a Create React App project.","error":"Module not found: Error: Can't resolve 'your-component' in '.../src'"},{"fix":"Review the `WebpackDevServerUtils` source or latest `react-scripts` webpack configuration to understand the current usage. Ensure `WebpackDevServer` is correctly imported (e.g., `import WebpackDevServer from 'webpack-dev-server';`) and its constructor is called with the expected arguments, often including a configuration object and a webpack compiler instance.","cause":"This indicates an incorrect or outdated usage of `WebpackDevServerUtils`, possibly due to changes in its internal structure or how `WebpackDevServer` is expected to be imported or instantiated.","error":"TypeError: Cannot read properties of undefined (reading 'WebpackDevServer')"},{"fix":"If you have a custom `.eslintrc` file or ESLint plugins, update them to be compatible with ESLint v8. Check the ESLint v8 migration guide for details on rule changes and plugin compatibility. Ensure all ESLint-related packages are also updated to their latest versions.","cause":"Upgrading `react-scripts` to v5.0.0 (which includes `react-dev-utils` v12.0.1) also upgrades ESLint to v8. This can lead to breaking changes in ESLint configurations, especially regarding plugin resolution or rule changes.","error":"ESLint encountered a parsing error or cannot resolve plugin '...' after upgrading Create React App."}],"ecosystem":"npm"}