CYCLEHOUND · CIRCULAR IMPORT CHECKER · RUST + WEBASSEMBLY · RUNS IN YOUR BROWSER

Which of your files import each other in a circle?

Pick a JavaScript or TypeScript project folder and cyclehound draws its import graph, then lists every loop in it: which files, and the file and line of each import that closes the loop. A loop works until the day a module uses something it imported while the files are still loading; this shows you the loops before that day.

Nothing is uploaded. Your files are read by this tab and given to a WebAssembly module from this site; the page makes no network requests of its own after it loads.

1. Pick a folder, or paste a few files

Reads .js .mjs .cjs .jsx .ts .mts .cts .tsx files and skips node_modules, .git and target. Imports that point outside the folder you pick show up as unresolved, because the page cannot see those files.

Or paste files

Untick all three to see only the loops that run when the files load: type imports are erased before the code runs, and import() waits until it is called.

How it works

  1. Read the imports of every file with a small lexer that skips comments, strings, template literals and regular expressions, so "import x from './y'" inside a string is not an import. It finds import ... from, import "x", export ... from, import("x") and require("x"), each with its line number.
  2. Resolve each relative import the way bundlers and TypeScript do: the exact file, then each extension, then index in a folder, and ./x.js written for a file that is really x.ts. Aliases such as @/lib/x go through the paths and baseUrl of the nearest tsconfig.json or jsconfig.json, following extends, by TypeScript's rules. Package imports are left out.
  3. Group the files into strongly connected components (Tarjan's algorithm): sets in which every file can reach every other through imports. Every circular import lives inside one.
  4. List a shortest loop through each file of each component, with duplicates removed, so every file on a loop is shown and each loop is as short as it can be.

Measured, not promised

On the ventures/ folder of this project's own repository (11,422 .mjs files reached, 9,417 imports between them), on a 4-core cloud container, 2026-11-13:

ToolTimePeak memoryGraph
madge 8.0.0 (Node 22), --circular14.1 to 17.8 s327 to 363 MBreference
dependency-cruiser 16.10.4, every module type51.8 s2,272 MBsame edges, plus CSS imports
cyclehound CLI (native, 4 threads)0.19 to 0.26 s17 to 20 MBidentical to madge's

With --no-require, cyclehound's graph equals madge's exactly: the same 11,422 files and the same 9,417 edges. By default it also counts two require() calls inside .mjs test files that madge's ES-module reader skips. Against dependency-cruiser, with type-only imports left out (its default), every edge cyclehound found was in its graph too, and the only edges it had that cyclehound did not were 11 imports of CSS files, which cyclehound does not treat as modules. The method, the commands and where the tools differ are in the benchmark write-up.

On the command line

git clone --depth 1 --filter=blob:none --sparse https://github.com/duncan-haywood/oss-monorepo
cd oss-monorepo && git sparse-checkout set ventures/cyclehound
cargo install --path ventures/cyclehound

cyclehound src/                                  # every loop; exit 1 if there is one (a CI gate)
cyclehound --no-type --no-dynamic src/           # only loops that run at load time
cyclehound --json src/ > cycles.json              # components, loops, edges with line numbers
cyclehound --graph --json src/ > graph.json       # the whole graph, in madge's --json shape
cyclehound --unresolved src/                     # relative or alias imports that point at no file
cyclehound --orphans src/                        # files nothing imports
cyclehound --unused-exports src/                 # exports no file imports (ts-unused-exports' job)

Needs a Rust toolchain (rustup). Respects .gitignore. cyclehound --help lists every option.

When to use something else

Questions

Is my code uploaded?

No. The folder you pick is read by this browser tab and handed to a WebAssembly module loaded from this site. The page makes no network requests of its own after it loads.

Is a circular import a bug?

Not by itself. ES modules allow cycles, and code that only uses the imported names inside functions works. A cycle breaks when a module uses an imported value while the files are still loading, which depends on which file loads first, so it can pass every test and fail when someone adds a new entry point. Cycles are worth knowing about and usually worth removing.

How is this different from madge?

On 11,422 .mjs files madge 8.0.0 took 14 to 18 seconds and about 350 MB; cyclehound took 0.2 seconds and 20 MB and produced the same graph, edge for edge, once its require() edges were switched off. madge draws graph images, has many configuration options and reads webpack aliases; cyclehound does not. Both read TypeScript and jsconfig paths.

Why does it list fewer cycles than madge?

It groups files into components first: every file in a component can reach every other through imports. Then it lists a shortest cycle through each file. Every file on any cycle appears, but the list stays short; the number of distinct cycles in a tangled component can grow very fast.