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.
2. What imports what in a circle
Relative imports that point at no file
| File | Line | Import |
|---|
How it works
- 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 findsimport ... from,import "x",export ... from,import("x")andrequire("x"), each with its line number. - Resolve each relative import the way bundlers and TypeScript do: the exact file, then each extension, then
indexin a folder, and./x.jswritten for a file that is reallyx.ts. Aliases such as@/lib/xgo through thepathsandbaseUrlof the nearesttsconfig.jsonorjsconfig.json, followingextends, by TypeScript's rules. Package imports are left out. - 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.
- 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:
| Tool | Time | Peak memory | Graph |
|---|---|---|---|
madge 8.0.0 (Node 22), --circular | 14.1 to 17.8 s | 327 to 363 MB | reference |
| dependency-cruiser 16.10.4, every module type | 51.8 s | 2,272 MB | same edges, plus CSS imports |
| cyclehound CLI (native, 4 threads) | 0.19 to 0.26 s | 17 to 20 MB | identical 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
- madge when you want a picture of the graph, or your imports go through webpack or Vite aliases: madge reads those settings and cyclehound does not. TypeScript and jsconfig
pathsit does read. - dependency-cruiser when you want rules beyond cycles: which folders may import which, banned packages, orphans by pattern, and its many report formats.
- Your linter's import rules (for example
import/no-cyclein eslint-plugin-import) when you want the warning in your editor as you type.
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.