Build configuration plugins

Modify build configurations without rewriting them!

Mosaic provides an opportunity to modify Webpack and Babel configurations of a project from an isolated module, similarly to the runtime plugins, but not quite.

In CRA setups, CRACO plugin API is available instead of this one.

Preparations

In order to declare a build configuration plugin, some preparations are necessary. First of all, an extension module must be created. You will implement your plugin there.

For the development purposes, it's recommended to have the under-development extension module installed into your project.

Declare a build configuration plugin

Then, in your module, you should create a build configuration plugin declaration file, and reference it from your package.json. It is commonly accepted to create such plugins in build-config directory in the root of your module.

Any module can have unlimited amount of such plugins. If the module is enabled, or used as a parent theme - its build configuration plugins will be present in the application.

{
    "mosaic": {
        "build": {
            "plugins": ["./build-config/plugin-file.js"]
        }
    }
}

The guide below describes the process of implementing logic in this plugin declaration file.

Modify the configurations

A build configuration plugin declaration file is a CJS module, which exports a single object with plugin property.

This plugin property defines at least one of the two fields visible below.

Each field provides a function, which accepts a Webpack or Babel configuration object (correspondingly). This function processes the configuration object and returns a new value, used as a corresponding configuration further in the application. It is commonly accepted to mutate the configuration within these functions.

module.exports = {
    plugin: {
        overrideWebpackConfig: (webpackConfig) => {
            // TODO modify webpack config
        
            return webpackConfig;
        },
        overrideBabelConfig: (babelConfig) => {
            // TODO modify babel config
        
            return babelConfig;
        }
    }
};

Despite the resemblance with CRACO plugins, this API is not related to CRACO.