Rollup "Circular dependency" Warning - Fix Import Cycles in CI

Rollup detected an import cycle - module A imports B, which (transitively) imports A. It is a warning by default, but cycles cause subtle "undefined at module init" bugs and fail any build configured to treat warnings as errors.

What this error means

The build prints Circular dependency: <a> -> <b> -> <a>. On its own it is a warning; in a strict CI build (warnings-as-errors, or onwarn that throws) it fails the build, and at runtime it can yield an unexpectedly undefined import.

(!) Circular dependency
src/store/index.ts -> src/store/user.ts -> src/store/index.ts

# in a strict build this is escalated:
Error: Build failed: circular dependency treated as error

Common causes

Two modules import each other

A direct or transitive cycle, often through a barrel index.ts that re-exports modules which import back from the barrel.

Barrel file re-export loop

A barrel that re-exports many modules which each import from the barrel creates a large cycle, and the order of initialization can leave an import temporarily undefined.

How to fix it

Break the cycle

1. Move the shared symbol into a third module both sides import, instead of importing each other.
2. Import the concrete module directly rather than through a barrel that loops back.
3. Defer the import to call time (inside a function) where a value-at-init cycle would otherwise bite.

Surface cycles deliberately in CI

If you want cycles to fail the build, handle them explicitly in onwarn rather than silently ignoring.

// rollup.config.js
onwarn(warning, warn) {
  if (warning.code === 'CIRCULAR_DEPENDENCY') throw new Error(warning.message)
  warn(warning)
}

How to prevent it

• Avoid barrel files that re-export modules which import back from the barrel.
• Factor shared symbols into a leaf module both sides import.
• Decide intentionally whether cycles are warnings or errors in CI.

Related guides