Rspack Circular Dependency Plugin

It is intended to support all configuration options of circular-dependency-plugin (currently, namely cwd is not implemented)

The Plugin

Detect modules with circular dependencies when bundling with rspack.

Circular dependencies are often a necessity in complex software, the presence of a circular dependency doesn't always imply a bug, but in the case where you believe a bug exists, this module may help find it.

Basic Usage

// rspack.config.js
const RspackCircularDependencyPlugin = require("rspack-circular-dependency-plugin");

module.exports = {
    entry: "./src/index",
    plugins: [
        new RspackCircularDependencyPlugin({
            // exclude detection of files based on a RegExp
            exclude: /a\.js|node_modules/,
            // include specific files based on a RegExp
            include: /dir/,
            // add errors to rspack instead of warnings
            failOnError: true,
            // allow import cycles that include an asyncronous import,
            // e.g. via import(/* webpackChunkName: "dashboard" */ './file.js')
            allowAsyncCycles: false,
        }),
    ],
};

Advanced Usage

// rspack.config.js
const RspackCircularDependencyPlugin = require("rspack-circular-dependency-plugin");

module.exports = {
    entry: "./src/index",
    plugins: [
        new RspackCircularDependencyPlugin({
            // `onStart` is called before the cycle detection starts
            onStart({ compilation }) {
                console.log("start detecting rspack modules cycles");
            },
            // `onDetected` is called for each module that is cyclical
            onDetected({ paths, compilation }) {
                // `paths` will be an Array of the relative module paths that make up the cycle
                compilation.errors.push(new Error(paths.join(" -> ")));
            },
            // `onEnd` is called before the cycle detection ends
            onEnd({ compilation }) {
                console.log("end detecting rspack modules cycles");
            },
        }),
    ],
};

If you have some number of cycles and want to fail if any new ones are introduced, you can use the life cycle methods to count and fail when the count is exceeded. (Note if you care about detecting a cycle being replaced by another, this won't catch that.)

// rspack.config.js
const RspackCircularDependencyPlugin = require("rspack-circular-dependency-plugin");

const MAX_CYCLES = 5;
let numCyclesDetected = 0;

module.exports = {
    entry: "./src/index",
    plugins: [
        new RspackCircularDependencyPlugin({
            onStart({ compilation }) {
                numCyclesDetected = 0;
            },
            onDetected({ paths, compilation }) {
                numCyclesDetected++;
                compilation.warnings.push(new Error(paths.join(" -> ")));
            },
            onEnd({ compilation }) {
                if (numCyclesDetected > MAX_CYCLES) {
                    compilation.errors.push(
                        new Error(
                            `Detected ${numCyclesDetected} cycles which exceeds configured limit of ${MAX_CYCLES}`,
                        ),
                    );
                }
            },
        }),
    ],
};