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.

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.