Registry / devops / rollup-plugin-circular-dependencies

rollup-plugin-circular-dependencies

library2.0.1jsnpmunverified

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.

devops

npm install rollup-plugin-circular-dependencies

github ↗package ↗

INSTALL

IMPORT

SIG · ROLLUP-PLUGIN-CIRC

rollup-plugin-circular-dependencies

devopsjavascriptv2.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

circularDependencies

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

✗ const circularDependencies = require('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

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

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

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

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`); } }) ] };

Debug

Known issues

breakingDropped Rollup v2 support in v2.0.0

fix

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

affects: >=2.0.0 <2.0.0

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

affects: <1.2.0-rc.6

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

affects: >=1.2.0-rc.6

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

affects: >=1.0.0

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

affects: >=1.0.0

Errors

Common errors & fixes

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

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'`

TypeError: circularDependencies is not a function

Default import used instead of named import in ESM context

fix

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

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

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

Upgrade

Version history

2.0.1latest on npm

Audit

Dependencies

rolluprequiredPeer dependency; plugin is designed for Rollup >=3.0.0

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/rushelex/rollup-plugin-circular-dependencies ↗

packagehttps://www.npmjs.com/package/rollup-plugin-circular-dependencies ↗