rollup-plugin-circular-dependencies

2.0.1 verified Mon Apr 27 auth: no javascript

A Rollup/Vite plugin for detecting and reporting circular dependencies using Tarjan's algorithm. Current stable version is 2.0.1, released February 2026. Replaces Rollup's built-in circular dependency warnings with configurable output, including pretty-printed console logs, JSON file reports, per-cycle filtering, lifecycle hooks, and detection metrics. Supports Rollup 3 and 4, Node.js >=20.12.0, ships TypeScript types, and works with both ESM and CJS. Differentiator: rich formatting, lifecycle hooks, and watch mode support not found in similar plugins like rollup-plugin-cycle.

Common errors

error Error: Cannot find module 'rollup-plugin-circular-dependencies' ↓

cause Package not installed or import path typo

fix

Run npm install -D rollup-plugin-circular-dependencies and ensure your rollup config uses the exact import: import { circularDependencies } from 'rollup-plugin-circular-dependencies'

error TypeError: circularDependencies is not a function ↓

cause Default import used instead of named import in ESM context

fix

Use named import: import { circularDependencies } from 'rollup-plugin-circular-dependencies'

error The requested module 'rollup-plugin-circular-dependencies' does not provide an export named 'Options' ↓

cause Options is a TypeScript type, not a runtime value; importing it with destructuring fails at runtime

fix

Use import type { Options } from 'rollup-plugin-circular-dependencies' or omit the import if not needed

Warnings

breaking Dropped Rollup v2 support in v2.0.0 ↓

fix Upgrade to Rollup >=3.0.0. If you must use Rollup v2, stay on v1.x.

deprecated ESM dependencies removed; the package now ships ESM and CJS natively starting from v1.2.0-rc.6 ↓

fix Upgrade to v1.2.0-rc.6 or later for native ESM/CJS support.

breaking Node.js version requirement raised to >=20.12.0 in v1.2.0-rc.6 ↓

fix Ensure your Node.js version is >=20.12.0. Use nvm to update.

gotcha Plugin crashes on build if circular dependencies are found and throwOnError is true (default) ↓

fix Set throwOnError: false in options to only emit warnings instead of errors.

gotcha Mutual imports with different file extensions (e.g., .js vs .ts) can cause false positives/negatives ↓

fix Ensure consistent file extensions or use Rollup's resolve plugin to normalize.

Install

npm install rollup-plugin-circular-dependencies

yarn add rollup-plugin-circular-dependencies

pnpm add rollup-plugin-circular-dependencies

Imports

circularDependencies

wrong

const circularDependencies = require('rollup-plugin-circular-dependencies')

correct

import { circularDependencies } from 'rollup-plugin-circular-dependencies'

ESM-only; CJS require() will not work because package type is module.

DefaultFormatters
```
import { DefaultFormatters } from 'rollup-plugin-circular-dependencies'
```
DefaultFormatters is a named export, not a default export. Use object destructuring.

type Options

wrong

import { Options } from 'rollup-plugin-circular-dependencies'

correct

import type { Options } from 'rollup-plugin-circular-dependencies'

Options is only a TypeScript type, not a runtime value. Use 'import type' to avoid runtime errors.

Quickstart

Rollup configuration using the plugin with options: warning mode, custom JSON formatter, and lifecycle hook.

// rollup.config.js
import { circularDependencies } from 'rollup-plugin-circular-dependencies';
import json from '@rollup/plugin-json';

export default {
  input: 'src/index.js',
  output: {
    dir: 'dist',
    format: 'esm'
  },
  plugins: [
    json(),
    circularDependencies({
      throwOnError: false,
      formatOut: (data) => JSON.stringify(data, null, 2),
      onDetected: (data) => {
        console.log(`Detected ${data.cycles.length} cycles`);
      }
    })
  ]
};