Circular dependencies in newly migrated repository

[zmelendez-cbs]

Summary

I was tasked at work with migrating an existing NextJS web application to Turborepo to allow for code-sharing between any new applications that may be developed, as well as streamlined CI/CD and task caching.

Upon migration, it seemed like things would be relatively easy, as within our src directory in the NextJS app, we had folders containing any helper functions, components, contexts, etc., that I went and created as packages within the monorepo.

Whenever I went and executed this idea, it seemed to work fine, I created packages with labels such as @app/components, @app/hooks, @app/contexts, and then went on to change the import within the pages directory to accommodate for these new locations.

All seemed well, and I got through the migration without any TS errors after quite a bit of work, until I went to run the yarn dev command, and I got hit with:

Invalid package dependency graph: cyclic dependency detected:
  │     @app/lib, @app/utils, @app/components, @app/contexts

I see that I am importing some of these packages within others, but I don't understand what needs to be done to prevent this? As it seems to prevent this from happening, we would need to remove some exports that exist in a package like @app/lib and put it in @app/components? It seems counterintuitive to do it this way though, and I am unsure if I should continue with Turborepo.

Additional information

No response

Example

No response

[anthonyshew]

Circular dependencies happen when you have dependencies installed into each other such that an order for the package graph can't be determined to have a specific "direction".

For instance, given two packages with these package.jsons:

// ./packages/a/package.json
 {
   "name": "@repo/a",
   "scripts": {
     "build": "tsc"
   },
   "dependencies": {
     "@repo/b": "workspace:*"
    }
 }

// ./packages/b/package.json
 {
   "name": "@repo/b",
    "scripts": {
     "build": "tsc"
   },
   "dependencies": {
     "@repo/a": "workspace:*"
    }
 }

In this case, there's no way for turbo to understand which "build" to run first. If @repo/a needs @repo/b to be available for it to build, @repo/b needs to be built first...But how would it do that when @repo/b needs assets from @repo/a to be built?!

Some strategies to avoid this:

• Audit how you're using modules between your packages and see if there are some modules that should be moved to remove the cycles.
• Introduce an @repo/c package that holds the common utilities for @repo/a and @repo/b that will be built first before the other packages.
• Combining packages can also reduce the potential for cycles. I'm seeing @app/lib and @app/utils. Assuming those are both utility packages, could they be combined? Same for @app/components and @app/contexts. Assuming those are referring to the React concepts, could they be combined?

[zmelendez-cbs]

Hey @anthonyshew, thanks for the breakdown! I was able to get a graph showing all the circular dependencies, and it seems like there are a ton of them. I was hoping for an easy solution, but I will need to do exactly what you say and combine a few packages, as well as introduce new ones to combat the issue.

[anthonyshew]

Glad to get you unblocked. Know that your pain is heard and that you're not alone and adding Turborepo to an existing repository with circular dependencies is on our minds. We want to be able to ease that path in the future.

[AhmedBaset]

Can Turbo log what's exactly the package that causes the problem? I have a hard time figure out where is it.

Update: fixed but it'd be much better if the logs have more details.

[austinm911]

Agree having better logs would be appreciated greatly

[mrmckeb]

Hey @anthonyshew, I feel like there should be a way to force Turborepo to accept the circular dependency in this scenario.

Take this case where eslint-config <-> vitest-config:

• The Vitest config is in TypeScript, and we want to lint that code.
• The ESLint config is TypeScript, and has custom rules, so we want to be able to run tests on that code.

We could break the rules out into a separate package, but then we end up with eslint-config <-> eslint-rules.

For now, my workaround is to directly import the shared Vitest config by relative path, and add that package as an arbitrary dependency in turbo.json.

[anthonyshew]

It'd be great if we could accept cycles, but that quickly runs against the fundamentals of a directed acyclic graph. Our internal structure of your repo heavily depends on the package graph and being able to construct a well-formed DAG.

I've tried to think of ways we could let people build an acyclic graph that's definitely a cyclic graph and the only thing I can think of is with a --dangerously-allow-package-graph-cycles that lets you accept the risks yourself.

[mrmckeb]

Thanks Anthony. I understand why this is a hard error, but as mentioned there are the occasional cases where this is the only way. Tools like pnpm handle these relationships, but they aren't worried about build order, etc.

If cycles were allowed, I'm guessing the main concern is task order? Could this be something that the user is required to supply alongside the "opt in" approach?