oxcruise

Validate and visualise your JS/TS module graph. A dependency-cruiser alternative built on the oxc toolchain.

npx oxcruise src

error[circular-dependencies]: circular dependency: src/a.ts → src/b.ts → src/a.ts
  --> src/a.ts:1:19
   |
 1 | import { b } from "./b";
   |                   ^^^^^
   = cycle:
     ╭─▶ src/a.ts
     ╰── src/b.ts

✖ 1 problem (1 error, 0 warnings) in 24 modules, 31 dependencies

It needs no config to start. The default rules catch circular imports, unresolvable imports, undeclared and dev-only dependencies, and orphan modules. When you need more, you add layers, forbid rules and plugins.

Why

• Fast. Reading, parsing, extracting and resolving run in parallel on every core, and cycles are found with one pass over the whole graph. See the benchmarks.
• One parser, no peer dependencies. TS, TSX, MTS, CTS, JSX, Vue, Svelte and Astro, with exact type-only information. You do not install typescript.
• Monorepo-aware. The nearest tsconfig.json per file, workspace packages and #imports.
• Good defaults, few knobs. Like oxlint, rules come in categories (correctness is on as error, suspicious as warn), globs are the only pattern language, and cycles that exist only through import type are not reported.
• Rules that say what you mean. Layers, folder visibility, folder structure, {name} captures and ! negation in globs.
• Plugins in TypeScript that see the finished graph, plugin reporters, and a programmatic API for architecture tests.
• Unused code. Unused exports, dependencies and files, modelled on Knip.
• A migration path. oxcruise --migrate converts your .dependency-cruiser.* file and says what it could not carry over.

Quick start

Oxcruise needs Node.js 22.18 or later.

npm install --save-dev oxcruise
npx oxcruise                       # check the current folder with the default rules
npx oxcruise src                   # start at src instead
npx oxcruise --init                # write a starter oxcruise.config.ts

The command exits with 0 when there are no errors, 1 when there are errors, and 2 for a bad flag or config file.

Other things to try:

npx oxcruise --visualize                          # an interactive architecture site in ./oxcruise-report
npx oxcruise -f github                            # annotations in GitHub Actions
npx oxcruise --rules                              # the built-in rules by category
npx oxcruise --print-config                       # the config after defaults and `extends`

Add --deny-warnings or --max-warnings <N> to fail a CI run on warnings.

Configure

Write the config in oxcruise.config.ts, or in .oxcruiserc.json (comments allowed, and a $schema for editors):

// oxcruise.config.ts
import { defineConfig } from "oxcruise";

export default defineConfig({
  entries: ["src"],
  ignorePatterns: ["src/generated/**"], // .gitignore is always honoured
  categories: { correctness: "error", suspicious: "warn" }, // this is the default
  rules: {
    "circular-dependencies": "error",
    layers: {
      level: "error",
      layers: { ui: "src/ui/**", domain: "src/domain/**" },
      allow: { ui: ["domain"], domain: [] },
    },
  },
  forbid: [
    {
      name: "feature-isolation",
      message: "features must not import each other",
      from: "src/features/{feature}/**",
      to: ["src/features/**", "!src/features/{feature}/**"],
    },
    { name: "no-node-in-browser", from: "src/web/**", to: { kind: "builtin" } },
  ],
  overrides: [{ files: ["scripts/**"], rules: { "dev-dependencies-in-production": "off" } }],
});

To silence one violation, say why in a comment:

// oxcruise-ignore-next-line circular-dependencies -- the registry needs the plugin list
import { plugins } from "./plugins";

See Configuration and the config reference for every key.

Built-in rules

Run npx oxcruise --rules for the list on your version.

Category	Default	Rules
correctness	error	circular-dependencies, unresolved-dependencies, undeclared-packages, dev-dependencies-in-production, dependencies-on-tests, cross-package-relative-dependencies
suspicious	warn	orphan-modules, duplicate-packages, deprecated-dependencies, unused-exports, unused-packages, unused-modules
style	off	folder-structure
restriction	off	layers, visibility, optional-dependencies, peer-dependencies

The unused-code rules need exports, so they cost an extra walk. They are on by default. Set them to off in rules to skip it, add --production to leave tests out, and --fix to apply the automatic repairs. See Rules and categories and the rule reference.

Plugins and the API

A plugin rule runs over the finished graph:

import { definePlugin } from "oxcruise/plugin";

export default definePlugin({
  meta: { name: "acme" },
  rules: {
    "max-fan-out": {
      create: (ctx) => ({
        module(m) {
          /* ctx.report({ module: m, message }) */
        },
      }),
    },
  },
});

The same graph is available from code, for architecture tests:

This is the beginning of the README. Read the rest at the original. Read the full README ↗