Circular Includes should Report an Error

[Pink-Wolf]

Goals

1. Remove silent errors
2. Keep behaviour of dev and build the same

Non-Goals

1. Allow circular includes

Background

By "circular includes", I mean that there are 2 files that both includes and uses functions from the other. For example:

// file1:
import { b } from "./file2" // file1 includes b from file2
export function a(): string {
    return "A"
}
export function c(): string {
    return b() + ".C"
}

// file2:
import { a } from "./file1" // file2 includes a from file1
export function b(): string {
    return a() + ".B"
}

I was working on a project automatically build and hosted to Github Pages, and during for example this commit*, I saw no mistake when developing (where I was using "npm run dev") nor saw any when the website was automatically build (with "npm run build"). I therefore assumed the project was working correctly.

I only later (when looking at the build hosted through Github Pages) saw that no actual pages where being build, except 404.
Since there was no errors and it worked with "npm run dev", I had to slowly go through different versions of the website, building each to finally find the mistake: I had two files, both including the other.
Once found, the mistake was easy to fix.

No pages being built is clearly an error. An error only happening when building, and especially an error happening while "npm run build" reports none, is obviously horrible (the chance errors are not caught before they reach production is much higher).

I have not checked if it matters that I for example use static exports.

*The circular include, in this repository, was from:

• "TTRPGDocs/ttrpg.client/src/lib/Keyword.tsx" including "getAllOrigins" from "./data/origin",
• "TTRPGDocs/ttrpg.client/src/lib/data/origin.tsx" including "Keyword" from "../Keyword"

Proposal

While it would be useful for "npm run build" to handle circular includes (just like "npm run dev" seemingly can) I assume getting this to work reliably is actually much more difficult.

I therefore propose that "npm run build" simply checks for circular includes, and ends with an error if any are found.
This would solve goal 1.

I also propose that "npm run dev" checks for circular includes, and reports an error if any are found as well.
Stopping "npm run dev" from working with circular includes may be a too breaking change, but I believe an error that can be ignored is fine.
This would somewhat solve goal 2.

[victormoni]

Hi @Pink-Wolf

Short answer

I agree this should not fail silently. A circular import can “work” in dev (because modules are loaded incrementally) but fail during next build/static export where evaluation order matters. At minimum, Next.js could warn in dev and fail in build when a cycle is detected in the app’s module graph (excluding node_modules). That keeps dev UX friendly while preventing broken deploys.

Why it happens

ESM/TS allows cycles, but initialization order is not guaranteed. During SSR/static export a module may read a value from another module before it’s initialized, producing undefined, empty routes, or pages not emitted.

Some cycles only appear after re-exports (barrel files), so the error is non-obvious.

What would help (proposal)

1. Dev: surface a visible warning (not just console noise) with the cycle path, e.g. a.ts -> b.ts -> a.ts.

2. Build: fail the build with a clear error (opt-out via config for legacy repos).

3. Heuristics: ignore external packages; treat type-only imports (import type { X } from ...) as non-cycles since they erase at runtime; show the shortest cycle.

4. Implementation sketch: Next already builds a graph (Webpack/Turbopack). Run a cycle check on the graph after resolve. This is essentially what CircularDependencyPlugin/tools like madge do.

Workarounds you can use today

• ESLint rule (fast feedback in dev/CI):

.eslintrc

{
  "plugins": ["import"],
  "rules": {
    "import/no-cycle": ["error", { "ignoreExternal": true, "maxDepth": 1 }]
  }
}

• CI guard with madge:

# install
npm i -D madge

# script (exits non-zero on cycles)
madge --extensions ts,tsx --circular src

package.json

{ "scripts": { "check:cycles": "madge --extensions ts,tsx --circular src" } }

• Webpack plugin in Next (for projects still on the webpack pipeline):

// next.config.js (CJS)
const CircularDependencyPlugin = require('circular-dependency-plugin');

module.exports = {
  webpack: (config) => {
    config.plugins.push(
      new CircularDependencyPlugin({
        exclude: /node_modules/,
        failOnError: true,
        allowAsyncCycles: false
      })
    );
    return config;
  },
};

Refactor tips to break cycles

• Move shared types/functions into a third module (shared.ts) so A←→B becomes A→Shared←B.

• Use type-only imports or import() at usage sites where runtime coupling isn’t needed.

• Avoid “barrel” re-exports that make dependency direction unclear.

Conclusion

+1 to making cycles actionable in Next: warn in dev, error in build, with clear paths. Until then, enforcing import/no-cycle and/or madge in CI prevents the “works in dev, breaks in build” trap.

[icyJoseph]

While it is true that you should avoid circular dependencies, I don't think their presence is the only thing that leads to this issue, but a pattern further down within a cycle. I have used the tools in the comment above, and also dependency-cruiser, and I can tell ya most projects have circular dependencies - anyway long story short -

I wonder if this was the issue:

export default async function Keyword({ children }: { children: string | string[] }) {
    if (typeof (children) !== "string") children = children.join('')

    return (await GetKeywordRecord())[children]
}

Cuz, Keyword is used in the origin file, and an export from that file, is part of the GetKeywordRecord definition through updateKeywordRecord. I almost wonder if export on updateKeywordRecord would've also fixed this 🤔

And the reason why it surfaces in prod build, could be because of minification, which not only minifies, but mangles, and re-arranges code in safe ways.

The latter being my interest here... maybe the minifier did something that was not safe?