@craco/craco
Advanced tools
Create React App Configuration Override, an easy and comprehensible configuration layer for create-react-app.
@craco/craco is a configuration layer for Create React App (CRA) that allows you to customize the default CRA configuration without ejecting. It provides a way to override the Webpack configuration, Babel configuration, and other settings in a more flexible and maintainable way.
Webpack Configuration Override
This feature allows you to override the default Webpack configuration provided by Create React App. In this example, the CracoLessPlugin is used to customize the primary color in a LESS file.
const CracoLessPlugin = require('craco-less');
module.exports = {
plugins: [
{
plugin: CracoLessPlugin,
options: {
lessLoaderOptions: {
lessOptions: {
modifyVars: { '@primary-color': '#1DA57A' },
javascriptEnabled: true,
},
},
},
},
],
};Babel Configuration Override
This feature allows you to override the default Babel configuration. In this example, the Babel plugin for decorators is added to the configuration.
module.exports = {
babel: {
plugins: [
['@babel/plugin-proposal-decorators', { legacy: true }],
],
},
};ESLint Configuration Override
This feature allows you to override the default ESLint configuration. In this example, the 'no-console' rule is turned off.
module.exports = {
eslint: {
enable: true,
mode: 'extends',
configure: {
rules: {
'no-console': 'off',
},
},
},
};customize-cra is another package that allows you to override the default Create React App configuration without ejecting. It provides a set of utilities to customize Webpack, Babel, and other configurations. Compared to @craco/craco, customize-cra is more focused on providing utility functions for common customizations, whereas @craco/craco offers a more structured plugin system.
react-app-rewired is a package that lets you override the Create React App configuration without ejecting. It allows you to modify the Webpack configuration and other settings by providing a config-overrides.js file. Compared to @craco/craco, react-app-rewired is simpler but less flexible, as it does not offer a plugin system.
Create React App Configuration Override is an easy and comprehensible configuration layer for create-react-app.
Get all the benefits of create-react-app and customization without using 'eject' by adding a single configuration (e.g. craco.config.js) file at the root of your application and customize your eslint, babel, postcss configurations and many more.
All you have to do is create your app using create-react-app and customize the configuration file.
react-scripts versionWe are grateful to @timarney the creator of react-app-rewired for his original idea.
The configuration style of this plugin has been greatly influenced by Vue CLI.
By doing this you're breaking the "guarantees" that CRA provides. That is to say you now "own" the configs. No support will be provided. Proceed with caution.
Install the latest version of the package from npm:
$ npm i @craco/craco
Alternatively, you can install the latest alpha build:
$ npm i @craco/craco@alphaHowever, you should be aware that these versions are experimental.
Create a craco.config.js file in the root directory and configure CRACO:
my-app
├── node_modules
├── craco.config.js
└── package.json
Update the existing calls to react-scripts in the scripts section of your package.json file to use the craco CLI:
/* package.json */
"scripts": {
- "start": "react-scripts start",
+ "start": "craco start",
- "build": "react-scripts build",
+ "build": "craco build"
- "test": "react-scripts test",
+ "test": "craco test"
}
Start your app for development:
$ npm start
Or build your app:
$ npm run build
CRACO is configured with a craco.config.ts, craco.config.js, .cracorc.ts, .cracorc.js or .cracorc file, or a file specified in package.json. This file is divided into sections representing the major parts of what makes up the default create react app.
If there are multiple configuration files in the same directory, CRACO will only use one. The priority order is:
package.jsoncraco.config.tscraco.config.js.cracorc.ts.cracorc.js.cracorcBelow is a sample CRACO configuration file. Your final config file will be much shorter than this sample. See example CRACO configurations in Recipes.
Some sections have a mode property. When this is available there are 2 possible values:
extends: the provided configuration will extends the CRA settings (default mode)file: the CRA settings will be reset and you will provide an official configuration file for the plugin (postcss, eslint) that will supersede any settings.const { when, whenDev, whenProd, whenTest, ESLINT_MODES, POSTCSS_MODES } = require("@craco/craco");
module.exports = {
reactScriptsVersion: "react-scripts" /* (default value) */,
style: {
modules: {
localIdentName: ""
},
css: {
loaderOptions: { /* Any css-loader configuration options: https://github.com/webpack-contrib/css-loader. */ },
loaderOptions: (cssLoaderOptions, { env, paths }) => { return cssLoaderOptions; }
},
sass: {
loaderOptions: { /* Any sass-loader configuration options: https://github.com/webpack-contrib/sass-loader. */ },
loaderOptions: (sassLoaderOptions, { env, paths }) => { return sassLoaderOptions; }
},
postcss: {
mode: "extends" /* (default value) */ || "file",
plugins: [require('plugin-to-append')], // Additional plugins given in an array are appended to existing config.
plugins: (plugins) => [require('plugin-to-prepend')].concat(plugins), // Or you may use the function variant.
env: {
autoprefixer: { /* Any autoprefixer options: https://github.com/postcss/autoprefixer#options */ },
stage: 3, /* Any valid stages: https://cssdb.org/#staging-process. */
features: { /* Any CSS features: https://preset-env.cssdb.org/features. */ }
},
loaderOptions: { /* Any postcss-loader configuration options: https://github.com/postcss/postcss-loader. */ },
loaderOptions: (postcssLoaderOptions, { env, paths }) => { return postcssLoaderOptions; }
}
},
eslint: {
enable: true /* (default value) */,
mode: "extends" /* (default value) */ || "file",
configure: { /* Any eslint configuration options: https://eslint.org/docs/user-guide/configuring */ },
configure: (eslintConfig, { env, paths }) => { return eslintConfig; },
pluginOptions: { /* Any eslint plugin configuration options: https://github.com/webpack-contrib/eslint-webpack-plugin#options. */ },
pluginOptions: (eslintOptions, { env, paths }) => { return eslintOptions; }
},
babel: {
presets: [],
plugins: [],
loaderOptions: { /* Any babel-loader configuration options: https://github.com/babel/babel-loader. */ },
loaderOptions: (babelLoaderOptions, { env, paths }) => { return babelLoaderOptions; }
},
typescript: {
enableTypeChecking: true /* (default value) */
},
webpack: {
alias: {},
plugins: {
add: [], /* An array of plugins */
add: [
plugin1,
[plugin2, "append"],
[plugin3, "prepend"], /* Specify if plugin should be appended or prepended */
], /* An array of plugins */
remove: [], /* An array of plugin constructor's names (i.e. "StyleLintPlugin", "ESLintWebpackPlugin" ) */
},
configure: { /* Any webpack configuration options: https://webpack.js.org/configuration */ },
configure: (webpackConfig, { env, paths }) => { return webpackConfig; }
},
jest: {
babel: {
addPresets: true, /* (default value) */
addPlugins: true /* (default value) */
},
configure: { /* Any Jest configuration options: https://jestjs.io/docs/en/configuration */ },
configure: (jestConfig, { env, paths, resolve, rootDir }) => { return jestConfig; }
},
devServer: { /* Any devServer configuration options: https://webpack.js.org/configuration/dev-server/#devserver */ },
devServer: (devServerConfig, { env, paths, proxy, allowedHost }) => { return devServerConfig; },
plugins: [
{
plugin: {
overrideCracoConfig: ({ cracoConfig, pluginOptions, context: { env, paths } }) => { return cracoConfig; },
overrideWebpackConfig: ({ webpackConfig, cracoConfig, pluginOptions, context: { env, paths } }) => { return webpackConfig; },
overrideDevServerConfig: ({ devServerConfig, cracoConfig, pluginOptions, context: { env, paths, proxy, allowedHost } }) => { return devServerConfig; },
overrideJestConfig: ({ jestConfig, cracoConfig, pluginOptions, context: { env, paths, resolve, rootDir } }) => { return jestConfig },
},
options: {}
}
]
};
Usage for all "when" functions is the same, whenDev, whenProd, whenTest are shortcuts for when.
when(condition, fct, [unmetValue])
Usage:
const { when, whenDev } = require("@craco/craco");
module.exports = {
eslint: {
mode: ESLINT_MODES.file,
configure: {
formatter: when(process.env.NODE_ENV === "CI", require("eslint-formatter-vso"))
}
},
webpack: {
plugins: [
new ConfigWebpackPlugin(),
...whenDev(() => [new CircularDependencyPlugin()], [])
]
}
};
You can export your configuration as an object literal:
/* craco.config.js */
module.exports = {
...
}
a function:
/* craco.config.js */
module.exports = function({ env }) {
return {
...
};
}
a promise or an async function:
/* craco.config.js */
module.exports = async function({ env }) {
await ...
return {
...
};
}
Both options support a relative or an absolute path.
1- package.json (Recommended)
You can change the location of the craco.config.js file by specifying a value for cracoConfig in your package.json
file.
/* package.json */
{
"cracoConfig": "config/craco-config-with-custom-name.js"
}
2- CLI (For backward compatibility)
You can also change the location of the craco.config.js file by specifying the --config CLI option. This option
doesn't support Babel with Jest
/* package.json */
{
"scripts": {
"start": "craco start --config config/craco-config-with-custom-name.js"
}
}
Create React App (CRA) is intended to allow people to get started with writing React apps quickly. It does this by packaging several key components with a solid default configuration.
After some initial experimentation, many people find the default CRA is not quite the right fit. Yet, selecting and configuring a toolchain featuring all of the components CRA already offers is overwhelming.
CRACO allows you to enjoy the recognizable project structure of CRA while changing detailed configuration settings of each component.
Keep in mind that there are some configuration settings available to CRA without CRACO.
Getting exactly what you want may involve a combination of making changes your CRACO configuration file and by using some of the more limited but still important settings available in Create React App.
Before jumping into customizing your CRACO configuration, step back and think about each part of the problem you're trying to solve. Be sure to review these resources on the CRA configuration, as it may save you time:
postbuild commands in package.jsonAvoiding ejecting is a major goal for many CRACO users. However, if you're still learning toolchains and modern frontend workflows, it may be helpful to create a sample ejected CRA project to see how the default CRA app configures each of the components.
While CRACO's sample configuration file inherits directly from CRA's default settings, seeing the default CRA config in the ejected CRA file structure may give you useful perspective.
You may even want to try testing a change in the ejected app to better understand how it would be done with your CRACO config-based project.
The sample CRACO config file is meant to show possibilities for configuring your CRA-based project. Each section
contains a primary configuration area, loaderOptions or configure. These config areas are where you will make most
of your detailed changes.
You, (or perhaps your IDE) may have noticed that the sections have duplicate keys, i.e. loaderOptions is listed twice in the sample config file.
The reason for this is to allow you to choose between object literal or functionally defined configuration choices. There are a few reasons for this:
devServer: {
writeToDisk: true
}
devServer: (devServerConfig, { env, paths, proxy, allowedHost }) => {
devServerConfig.writeToDisk = true;
return devServerConfig;
}
To integrate with other tools, it's useful to have access to the configuration generated by CRACO.
That's what CRACO APIs are for. The current API support Jest and Webpack.
Accept a cracoConfig, a context object and options. The generated Jest config object is returned.
Warning:
createJestConfigdoes NOT acceptcracoConfigas a function. If yourcraco.config.jsexposes a config function, you have to call it yourself before passing it tocreateJestConfig.
createJestConfig(cracoConfig, context = {}, options = { verbose: false, config: null })
Usage:
/* jest.config.js */
const { createJestConfig } = require("@craco/craco");
const cracoConfig = require("./craco.config.js");
const jestConfig = createJestConfig(cracoConfig);
module.exports = jestConfig;
You can create Webpack DevServer and Production configurations using createWebpackDevConfig and createWebpackProdConfig.
Accept a cracoConfig, a context object and options. The generated Webpack config object is returned.
Warning: Similar to
createJestConfig, these functions do NOT acceptcracoConfigas a function. If yourcraco.config.jsexposes a config function, you have to call it yourself before passing it further.
createWebpackDevConfig(cracoConfig, context = {}, options = { verbose: false, config: null })
createWebpackProdConfig(cracoConfig, context = {}, options = { verbose: false, config: null })
Usage:
/* webpack.config.js */
const { createWebpackDevConfig } = require("@craco/craco");
const cracoConfig = require("./craco.config.js");
const webpackConfig = createWebpackDevConfig(cracoConfig);
module.exports = webpackConfig;
There are four hooks available to a plugin:
overrideCracoConfig: Let a plugin customize the config object before it's process by craco.overrideWebpackConfig: Let a plugin customize the webpack config that will be used by CRA.overrideDevServerConfig: Let a plugin customize the dev server config that will be used by CRA.overrideJestConfig: Let a plugin customize the Jest config that will be used by CRA.Important:
Every function must return the updated config object.
The function overrideCracoConfig let a plugin override the config object before it's process by craco.
If a plugin define the function, it will be called with the config object read from the craco.config.js file provided
by the consumer.
The function must return a valid config object, otherwise craco will throw an error.
The function will be called with a single object argument having the following structure:
{
cracoConfig: "The config object read from the craco.config.js file provided by the consumer",
pluginOptions: "The plugin options provided by the consumer",
context: {
env: "The current NODE_ENV (development, production, etc..)",
paths: "An object that contains all the paths used by CRA"
}
}
Plugin:
/* craco-plugin-log-craco-config.js */
module.exports = {
overrideCracoConfig: ({ cracoConfig, pluginOptions, context: { env, paths } }) => {
if (pluginOptions.preText) {
console.log(pluginOptions.preText);
}
console.log(JSON.stringify(cracoConfig, null, 4));
// Always return the config object.
return cracoConfig;
}
};
Registration (in a craco.config.js file):
const logCracoConfigPlugin = require("./craco-plugin-log-craco-config");
module.exports = {
...
plugins: [
{ plugin: logCracoConfigPlugin, options: { preText: "Will log the craco config:" } }
]
};
The function overrideWebpackConfig let a plugin override the webpack config object after it's been customized
by craco.
The function must return a valid config object, otherwise craco will throw an error.
The function will be called with a single object argument having the following structure:
{
webpackConfig: "The webpack config object already customized by craco",
cracoConfig: "The configuration object read from the craco.config.js file provided by the consumer",
pluginOptions: "The plugin options provided by the consumer",
context: {
env: "The current NODE_ENV (development, production, etc..)",
paths: "An object that contains all the paths used by CRA"
}
}
Plugin:
/* craco-plugin-log-webpack-config.js */
module.exports = {
overrideWebpackConfig: ({ webpackConfig, cracoConfig, pluginOptions, context: { env, paths } }) => {
if (pluginOptions.preText) {
console.log(pluginOptions.preText);
}
console.log(JSON.stringify(webpackConfig, null, 4));
// Always return the config object.
return webpackConfig;
}
};
Registration (in a craco.config.js file):
const logWebpackConfigPlugin = require("./craco-plugin-log-webpack-config");
module.exports = {
...
plugins: [
{ plugin: logWebpackConfigPlugin, options: { preText: "Will log the webpack config:" } }
]
};
The function overrideDevServerConfig let a plugin override the dev server config object after it's been customized
by craco.
The function must return a valid config object, otherwise craco will throw an error.
The function will be called with a single object argument having the following structure:
{
devServerConfig: "The dev server config object already customized by craco",
cracoConfig: "The configuration object read from the craco.config.js file provided by the consumer",
pluginOptions: "The plugin options provided by the consumer",
context: {
env: "The current NODE_ENV (development, production, etc..)",
paths: "An object that contains all the paths used by CRA",
allowedHost: "Provided by CRA"
}
}
Plugin:
/* craco-plugin-log-dev-server-config.js */
module.exports = {
overrideDevServerConfig: ({ devServerConfig, cracoConfig, pluginOptions, context: { env, paths, allowedHost } }) => {
if (pluginOptions.preText) {
console.log(pluginOptions.preText);
}
console.log(JSON.stringify(devServerConfig, null, 4));
// Always return the config object.
return devServerConfig;
}
};
Registration (in a craco.config.js file):
const logDevServerConfigPlugin = require("./craco-plugin-log-dev-server-config");
module.exports = {
...
plugins: [
{ plugin: logDevServerConfigPlugin, options: { preText: "Will log the dev server config:" } }
]
};
The function overrideJestConfig let a plugin override the Jest config object after it's been customized by
craco.
The function must return a valid config object, otherwise craco will throw an error.
The function will be called with a single object argument having the following structure:
{
jestConfig: "The Jest config object already customized by craco",
cracoConfig: "The configuration object read from the craco.config.js file provided by the consumer",
pluginOptions: "The plugin options provided by the consumer",
context: {
env: "The current NODE_ENV (development, production, etc..)",
paths: "An object that contains all the paths used by CRA",
resolve: "Provided by CRA",
rootDir: "Provided by CRA"
}
}
Plugin:
/* craco-plugin-log-jest-config.js */
module.exports = {
overrideJestConfig: ({ jestConfig, cracoConfig, pluginOptions, context: { env, paths, resolve, rootDir } }) => {
if (pluginOptions.preText) {
console.log(pluginOptions.preText);
}
console.log(JSON.stringify(jestConfig, null, 4));
// Always return the config object.
return jestConfig;
}
};
Registration (in a craco.config.js file):
const logJestConfigPlugin = require("./craco-plugin-log-jest-config");
module.exports = {
...
plugins: [
{ plugin: logJestConfigPlugin, options: { preText: "Will log the Jest config:" } }
]
};
A few utility functions are provided by CRACO to help you develop a plugin:
getLoadergetLoadersremoveLoadersaddBeforeLoaderaddBeforeLoadersaddAfterLoaderaddAfterLoadersgetPluginremovePluginsaddPluginsthrowUnexpectedConfigErrorconst { getLoader, getLoaders, removeLoaders, loaderByName, getPlugin, removePlugins, addPlugins, pluginByName, throwUnexpectedConfigError } = require("@craco/craco");
Retrieve the first loader that match the specified criteria from the webpack config.
Returns:
{
isFound: true | false,
match: {
loader,
parent,
index
}
}
Usage:
const { getLoader, loaderByName } = require("@craco/craco");
const { isFound, match } = getLoader(webpackConfig, loaderByName("eslint-loader"));
if (isFound) {
// do stuff...
}
Retrieve all the loaders that match the specified criteria from the webpack config.
Returns:
{
hasFoundAny: true | false,
matches: [
{
loader,
parent,
index
}
]
}
Usage:
const { getLoaders, loaderByName } = require("@craco/craco");
const { hasFoundAny, matches } = getLoaders(webpackConfig, loaderByName("babel-loader"));
if (hasFoundAny) {
matches.forEach(x => {
// do stuff...
});
}
Remove all the loaders that match the specified criteria from the webpack config.
Returns:
{
hasRemovedAny: true | false,
removedCount: int
}
Usage:
const { removeLoaders, loaderByName } = require("@craco/craco");
removeLoaders(webpackConfig, loaderByName("eslint-loader"));
Add a new loader before the loader that match specified criteria to the webpack config.
Returns:
{
isAdded: true | false
}
Usage:
const { addBeforeLoader, loaderByName } = require("@craco/craco");
const myNewWebpackLoader = {
loader: require.resolve("tslint-loader")
};
addBeforeLoader(webpackConfig, loaderByName("eslint-loader"), myNewWebpackLoader);
Add a new loader before all the loaders that match specified criteria to the webpack config.
Returns:
{
isAdded: true | false,
addedCount: int
}
Usage:
const { addBeforeLoaders, loaderByName } = require("@craco/craco");
const myNewWebpackLoader = {
loader: require.resolve("tslint-loader")
};
addBeforeLoaders(webpackConfig, loaderByName("eslint-loader"), myNewWebpackLoader);
Add a new loader after the loader that match specified criteria to the webpack config.
Returns:
{
isAdded: true | false
}
Usage:
const { addAfterLoader, loaderByName } = require("@craco/craco");
const myNewWebpackLoader = {
loader: require.resolve("tslint-loader")
};
addAfterLoader(webpackConfig, loaderByName("eslint-loader"), myNewWebpackLoader);
Add a new loader after all the loaders that match specified criteria to the webpack config.
Returns:
{
isAdded: true | false,
addedCount: int
}
Usage:
const { addAfterLoaders, loaderByName } = require("@craco/craco");
const myNewWebpackLoader = {
loader: require.resolve("tslint-loader")
};
addAfterLoaders(webpackConfig, loaderByName("eslint-loader"), myNewWebpackLoader);
Retrieve the first plugin that match the specified criteria from the webpack config.
Returns:
{
isFound: true | false,
match: {...} // the webpack plugin
}
Usage:
const { getPlugin, pluginByName } = require("@craco/craco");
const { isFound, match } = getPlugin(webpackConfig, pluginByName("ESLintWebpackPlugin"));
if (isFound) {
// do stuff...
}
Remove all the plugins that match the specified criteria from the webpack config.
Returns:
{
hasRemovedAny:: true | false,
removedCount:: int
}
Usage:
const { removePlugins, pluginByName } = require("@craco/craco");
removePlugins(webpackConfig, pluginByName("ESLintWebpackPlugin"));
Add new plugins to the webpack config.
Usage:
const { addPlugins } = require("@craco/craco");
const myNewWebpackPlugin = require.resolve("ESLintWebpackPlugin");
addPlugins(webpackConfig, [myNewWebpackPlugin]);
addPlugins(webpackConfig, [ [myNewWebpackPlugin, "append"] ]);
addPlugins(webpackConfig, [ [myNewWebpackPlugin, "prepend"] ]);
Throw an error if the webpack configuration changes and does not match your expectations. (For example, getLoader
cannot find a loader and isFound is false.) create-react-app might update the structure of their webpack config,
so it is very important to show a helpful error message when something breaks.
Raises an error and crashes Node.js:
$ yarn start
yarn run v1.12.3
$ craco start
/path/to/your/app/craco.config.js:23
throw new Error(
^
Error: Can't find eslint-loader in the webpack config!
This error probably occurred because you updated react-scripts or craco. Please try updating craco-less to the latest version:
$ yarn upgrade craco-less
Or:
$ npm update craco-less
If that doesn't work, craco-less needs to be fixed to support the latest version.
Please check to see if there's already an issue in the ndbroadbent/craco-less repo:
* https://github.com/ndbroadbent/craco-less/issues?q=is%3Aissue+webpack+eslint-loader
If not, please open an issue and we'll take a look. (Or you can send a PR!)
You might also want to look for related issues in the craco and create-react-app repos:
* https://github.com/sharegate/craco/issues?q=is%3Aissue+webpack+eslint-loader
* https://github.com/facebook/create-react-app/issues?q=is%3Aissue+webpack+eslint-loader
at throwUnexpectedConfigError (/path/to/your/app/craco.config.js:23:19)
...
Usage:
const { getLoader, loaderByName, throwUnexpectedConfigError } = require("@craco/craco");
// Create a helper function if you need to call this multiple times
const throwError = (message, githubIssueQuery) =>
throwUnexpectedConfigError({
packageName: "craco-less",
githubRepo: "ndbroadbent/craco-less",
message,
githubIssueQuery,
});
const { isFound, match } = getLoader(webpackConfig, loaderByName("eslint-loader"));
if (!isFound) {
throwError("Can't find eslint-loader in the webpack config!", "webpack+eslint-loader")
}
Options:
{
message: "An error message explaining what went wrong",
packageName: "NPM package name",
githubRepo: "GitHub repo where people can open an issue. Format: username/repo",
githubIssueQuery: "Search string to find related issues"
}
Only
messageis required.
CRACO is not meant to be backward compatible with older versions of react-scripts. This package will only support the latest version. If your project uses an old react-scripts version, refer to the following table to select the appropriate CRACO version.
| react-scripts Version | CRACO Version |
|---|---|
| react-scripts < 4.0.0 | 5.8.0 |
To activate verbose logging specify the CLI option --verbose
/* package.json */
{
"scripts": {
"start": "craco start --verbose"
}
}
Copyright © 2020, Groupe Sharegate inc. This code is licensed under the Apache License, Version 2.0. You may obtain a copy of this license at https://github.com/gsoft-inc/gsoft-license/blob/master/LICENSE.
FAQs
Create React App Configuration Override, an easy and comprehensible configuration layer for create-react-app.
The npm package @craco/craco receives a total of 232,179 weekly downloads. As such, @craco/craco popularity was classified as popular.
We found that @craco/craco demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team uncovered a malicious Python package typosquatting the popular 'fabric' SSH library, silently exfiltrating AWS credentials from unsuspecting developers.
Security News
At its inaugural meeting, the JSR Working Group outlined plans for an open governance model and a roadmap to enhance JavaScript package management.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.