tools.postcss#

• Type: Object | Function
• Default:

const defaultOptions = {
  postcssOptions: {
    config: false,
    sourceMap: rsbuildConfig.output.sourceMap.css,
  },
};

Rsbuild integrates PostCSS by default, you can configure postcss-loader through tools.postcss.

Function Type#

When tools.postcss is a function, the default options will be passed in as the first parameter. You can directly modify this object or return a new object as the final options to be used. For example:

For example, to add a PostCSS plugin, you can call the addPlugins utility function:

export default {
  tools: {
    postcss: (opts, { addPlugins }) => {
      addPlugins(require('postcss-px-to-viewport'));
    },
  },
};

If you need to pass parameters to the PostCSS plugin, you can call the PostCSS plugin as a function:

export default {
  tools: {
    postcss: (opts, { addPlugins }) => {
      const viewportPlugin = require('postcss-px-to-viewport')({
        viewportWidth: 375,
      });
      addPlugins(viewportPlugin);
    },
  },
};

You can also modify the default postcss-loader options:

export default {
  tools: {
    postcss: (opts) => {
      opts.sourceMap = false;
    },
  },
};

tools.postcss can return a config object and completely replace the default config:

export default {
  tools: {
    postcss: () => {
      return {
        postcssOptions: {
          plugins: [require('postcss-px-to-viewport')],
        },
      };
    },
  },
};

Object Type#

When tools.postcss is an object, it will be merged with the default configuration using Object.assign. Note that Object.assign is a shallow copy and will completely overwrite the built-in presets or plugins array, please use it with caution.

export default {
  tools: {
    postcss: {
      // As `Object.assign` is used, the default postcssOptions will be overwritten.
      postcssOptions: {
        plugins: [require('postcss-px-to-viewport')],
      },
    },
  },
};

Utils#

addPlugins#

• Type: (plugins: PostCSSPlugin | PostCSSPlugin[]) => void

For adding additional PostCSS plugins, You can pass in a single PostCSS plugin, or an array of PostCSS plugins.

export default {
  tools: {
    postcss: (config, { addPlugins }) => {
      // Add a PostCSS Plugin
      addPlugins(require('postcss-preset-env'));
      // Add multiple PostCSS Plugins
      addPlugins([require('postcss-preset-env'), require('postcss-import')]);
    },
  },
};

Practice#

Multiple PostCSS Options#

tools.postcss.postcssOptions can be set to a function, which receives the Rspack's loaderContext as a parameter. This allows you to use different PostCSS options for different file paths.

For example, use postcss-plugin-a for file paths containing foo, and use postcss-plugin-b for other file paths:

export default {
  tools: {
    postcss: {
      postcssOptions: (loaderContext) => {
        if (/foo/.test(loaderContext.resourcePath)) {
          return {
            plugins: [require('postcss-plugin-a')],
          };
        }
        return {
          plugins: [require('postcss-plugin-b')],
        };
      },
    },
  },
};

Notes#

PostCSS Version#

Rsbuild uses the PostCSS v8. When you use third-party PostCSS plugins, please pay attention to whether the PostCSS version is compatible. Some legacy plugins may not work in PostCSS v8.

PostCSS Config Loading#

Rsbuild uses postcss-load-config to load PostCSS config files and merge them with the default config.

Rsbuild internally sets the postcss-loader's postcssOptions.config option to false to avoid loading config files repeatedly.