How to fix Circular dependency between project references in TypeScript

First, examine your project structure to identify where the circular dependency occurs. Check all tsconfig.json files in your project:

// Example tsconfig.json with references
{
  "compilerOptions": {
    "composite": true
  },
  "references": [
    { "path": "../project-b" }  // Check if this creates a cycle
  ]
}

Look for any project that references another project which eventually references back to the original. You can create a visual diagram or list all references to trace the chain.

Restructure your project dependencies to eliminate the cycle. Consider these approaches:

1. Extract shared code: Move common code that both projects depend on into a third shared project
2. Merge projects: If two projects are tightly coupled, consider merging them into one
3. Change dependency direction: Determine which project should truly depend on the other

Example of fixing a direct cycle:

Before: Project A ↔ Project B (circular)
After: Project A → Shared → Project B (no cycle)

For complex monorepos, use TypeScript's composite project feature properly:

// In root tsconfig.json
{
  "files": [],
  "references": [
    { "path": "./packages/core" },
    { "path": "./packages/ui" },
    { "path": "./packages/utils" }
  ]
}

Each sub-project should have "composite": true and should only reference projects it truly depends on, not projects that depend on it.

After restructuring, verify the fix works:

1. Run tsc --build --verbose to see the build order
2. Check that all projects compile successfully
3. Test that your application still works correctly
4. Consider adding a pre-build script to detect cycles:

#!/bin/bash
# Simple cycle detection (pseudo-code)
# Check that no project references create cycles
# You could write a script that parses all tsconfig.json files

Implement practices to prevent circular dependencies from reoccurring:

1. Document dependency rules: Clearly define which projects can depend on others
2. Use dependency graphs: Tools like madge or dependency-cruiser can detect cycles
3. CI/CD checks: Add cycle detection to your build pipeline
4. Code reviews: Review tsconfig.json changes carefully when adding new references

Example using dependency-cruiser:

npx dependency-cruiser --config .dependency-cruiser.json src/

Create a .dependency-cruiser.json config file to define allowed and forbidden dependencies.