# vite-plugin-circular-dependency

> Detect circular dependencies

Latest version **0.6.0** (published 2026-05-06) · MIT license · 0 weekly downloads

## Install

```sh
npm install vite-plugin-circular-dependency
pnpm add vite-plugin-circular-dependency
yarn add vite-plugin-circular-dependency
bun add vite-plugin-circular-dependency
```

## Health

**Score 55/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.6.0 |
| Published | 2026-05-06 |
| First published | 2023-01-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 2 |
| Unpacked size | 19.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 51 |
| Author | threedayAAAAA |
| Maintainers | zstar01 |
| Keywords | vite-plugin, vite plugin, vite, dependencies, circular-dependencies |

## Links

- npm: https://www.npmjs.com/package/vite-plugin-circular-dependency
- Repository: https://github.com/threedayAAAAA/vite-plugin-circular-dependency
- Homepage: https://github.com/threedayAAAAA/vite-plugin-circular-dependency#readme
- Issues: https://github.com/threedayAAAAA/vite-plugin-circular-dependency/issues
- npm.io page: https://npm.io/package/vite-plugin-circular-dependency

## Dependencies (2)

- [chalk](https://npm.io/package/chalk.md) ^4.1.2
- [@rollup/pluginutils](https://npm.io/package/@rollup/pluginutils.md) ^5.1.0

## Alternatives

- [jsforce](https://npm.io/package/jsforce.md) — 851.2K weekly downloads
- [react-native-qrcode-svg](https://npm.io/package/react-native-qrcode-svg.md) — 693.5K weekly downloads
- [@salesforce/plugin-data](https://npm.io/package/@salesforce/plugin-data.md) — 394.9K weekly downloads
- [@backstage/plugin-search-common](https://npm.io/package/@backstage/plugin-search-common.md) — 308.5K weekly downloads
- [@chain-registry/types](https://npm.io/package/@chain-registry/types.md) — 38.4K weekly downloads

## Recent versions

- 0.6.0 (latest) — 2026-05-06
- 0.5.0 — 2024-09-30
- 0.4.2 — 2024-09-30
- 0.4.1 — 2024-03-25
- 0.4.0 — 2024-03-04
- 0.3.1 — 2024-02-08
- 0.3.0 — 2024-01-21
- 0.2.1 — 2023-02-25
- 0.2.0 — 2023-02-25
- 0.1.7 — 2023-01-18
- 0.1.6 — 2023-01-18
- 0.1.5 — 2023-01-17
- 0.1.4 — 2023-01-17
- 0.1.3 — 2023-01-17
- 0.1.2 — 2023-01-17
- … 3 more at https://npm.io/package/vite-plugin-circular-dependency/versions

## README

## vite-plugin-circular-dependency

English | [中文](README_zh.md)

A framework-agnostic build-time Vite plugin designed to detect circular imports and self-references, compatible with dynamic and static imports.

### DEMO

```js
// Configure the output path,
// a scan report will be generated to the specified path
export default defineConfig({
  plugins: [
    circleDependency({
      outputFilePath: "./circleDep",
    }),
  ],
});
```

![image](https://user-images.githubusercontent.com/38604634/221328375-8dc381f1-6895-4875-93a0-d3d675153894.png)

```js
// Without any configuration, it will be printed on the console
export default defineConfig({
  plugins: [circleDependency()],
});
```

![image](https://user-images.githubusercontent.com/38604634/221328836-62b58f09-c11c-4429-a143-e92ef9aefa9f.png)

### Installation

```ts
npm i -D vite-plugin-circular-dependency
// yarn add --dev vite-plugin-circular-dependency
// pnpm i --dev vite-plugin-circular-dependency
```

### Usage

Please use this plugin when building

In your `vite.config.(js|ts)` import the plugin and register it.

```typescript
import { defineConfig } from "vite";
import circleDependency from "vite-plugin-circular-dependency";

export default defineConfig({
  plugins: [circleDependency()],
});
```

### Options

```ts
export interface Options {
  /**
   * Rules to include transforming target.
   *
   * @default [/\.[jt]sx?$/, /\.vue\??/]
   */
  include?: FilterPattern;

  /**
   * Rules to exclude scan target.
   *
   * @default [/node_modules/, /\.git/]
   */
  exclude?: FilterPattern;

  /**
   * The file address of the scan result output, the default console print
   */
  outputFilePath?: string;

  // If configured, will output the products of circular references as an interactive HTML application to the specified address
  outputInteractiveFilePath?: string;

  /**
   * Whether to throw an error when a circular import exists
   *
   * @default true
   */
  circleImportThrowErr?: boolean;

  /**
   * Format the path of the output node.
   * By default, vite.config will be used as the root path to generate a relative path
   *
   * @default function
   */
  formatOutModulePath?: (path: string) => string;

  /**
   * The result of formatted output
   * will also affect the data format in the console print or output file
   *
   * @default (data: CircleData) => data
   */
  formatOut?: (data: CircleData) => any;

  /**
   * Whether to ignore dynamic imports during the scan.
   *
   * @default false
   *
   * If the file has the @circular-ignore tag, the module will also be ignored for circular dependency scanning.
   * Example:
   * // @circular-ignore
   * import { example } from './exampleModule';
   */
  ignoreDynamicImport?: boolean;
}
```

---
_Source: https://npm.io/package/vite-plugin-circular-dependency · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._