@craco/craco

What is @craco/craco?

@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.

What are @craco/craco's main functionalities?

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',
      },
    },
  },
};

Other packages similar to @craco/craco

customize-cra

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

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.

README

craco

Create React App Configuration Override is an easy and comprehensible configuration layer for create-react-app v2.

Get all the benefits of create-react-app and customization without using 'eject' by adding a single 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 with a craco.config.js file.

• CLI Options - Available CLI options.
• Configuration Overview - Quickly see how you can configure your CRA installation with this plugin.
• Recipes – Short recipes for common use cases.
• Available Plugins - Plugins maintained by the community.
• Develop a Plugin - How to develop a plugin for craco.
• Changelog - List of major changes

Acknowledgements:

We are grateful to @timarney the creator of react-app-rewired for his original idea.

Also, please note that the configuration style of this plugin has been greatly influenced by the way Vue CLI does it.

Please Note:

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.

You updated craco and everything falls apart

Before logging an issue, please consult the changelog.

If you can't find any solution to your problem in the changelog, log an issue and someone should help you quickly!

Installation

Install the plugin from npm:

$ yarn add @craco/craco

# OR

$ npm install @craco/craco --save

Create a craco.config.js file in the root directory:

my-app
├── node_modules
├── craco.config.js
└── package.json

Export your configuration as an object literal:

/* craco.config.js */

module.exports = {
    ...
}

or a function:

/* craco.config.js */

module.exports = function({ env, paths }) {
    return {
        ...
    };
}

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

CLI Options

When you execute craco start or craco build a few options are available.

To change the location of the configuration file:

"scripts": {
    "start": "craco start --config config/craco-config-with-custom-name.js"
}

To use with a yarn workspace or any monorepo setup that follows the popular convention packages/*:

"scripts": {
    "start": "craco start --workspace"
}

To use with a different version of react-scripts:

"scripts": {
    "start": "craco start --scripts-version react-scripts-ts"
}

To provided a custom path for the react-scripts folder:

"scripts": {
    "start": "craco start --react-scripts ../../react-scripts-with-custom-name"
}

The provided react-scripts folder path must be relative to the current working directory.

If --react-scripts is provided, --workspace and --scripts-version will be ignored.

To activate verbose logging:

"scripts": {
    "start": "craco start --verbose"
}

Configuration Overview

When the property mode is available there are 2 possible values:

• extends: the provided configuration will extends the CRA settings (default mode)
• file: the CRA settings will be reseted and you will provide an official configuration file for the plugin (postcss, eslint) that will supersede any settings.

const { paths, when, whenDev, whenProd, whenTest, ESLINT_MODES, POSTCSS_MODES } = require("@craco/craco");

module.exports = {
    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: [],
            loaderOptions: { /* Any postcss-loader configuration options: https://github.com/postcss/postcss-loader. */ },
            loaderOptions: (postcssLoaderOptions, { env, paths }) => { return postcssLoaderOptions; }
        }
    },
    eslint: {
        enable: true,
        mode: "extends" /* (default value) */ || "file",
        configure: { /* Any eslint configuration options: https://eslint.org/docs/user-guide/configuring */ },
        configure: (eslintConfig, { env, paths }) => { return eslintConfig; },
        loaderOptions: { /* Any eslint-loader configuration options: https://github.com/webpack-contrib/eslint-loader. */ },
        loaderOptions: (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; }
    },
    webpack: {
        alias: {},
        plugins: [],
        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; },
                overrideJestConfig: ({ jestConfig, cracoConfig, pluginOptions, context: { env, paths, resolve, rootDir } }) => { return jestConfig };
            },
            options: {}
        }
    ]
};

Develop a plugin

There are 3 functions 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.
• overrideJestConfig: Let a plugin customize the Jest config that will be used by CRA.

Important:

Every functions must return the updated config object.

overrideCracoConfig

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"
    }
}

Example

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(craconfig, 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:" } }
    ]
};

overrideWebpackConfig

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"
    }
}

Example

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:" } }
    ]
};

overrideJestConfig

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"
    }
}

Example

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:" } }
    ]
};

Utility functions

A few utility functions are provided by craco to develop a plugin:

const { getLoader, getLoaders, removeLoader, loaderByName, throwUnexpectedConfigError } = require("@craco/craco");

getLoader

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...
}

getLoaders

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...
    });
}

removeLoaders

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"));

addBeforeLoader

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);

addBeforeLoaders

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);

addAfterLoader

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);

addAfterLoaders

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);

throwUnexpectedConfigError

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 message is required.

Acknowledgements

@timarney for having created react-app-rewired.

License

Copyright © 2018, 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/sharegate/craco/blob/master/LICENSE.