How to fix Project 'X' cannot reference itself in TypeScript

TypeScriptINTERMEDIATEMEDIUM

This TypeScript error occurs when a project references itself in its own tsconfig.json file, creating a circular dependency. This typically happens in monorepos or project reference configurations where a project accidentally includes itself in its references array. The fix involves removing the self-reference from the references array.

What this error means

The "Project cannot reference itself" error appears when TypeScript's project references feature detects a circular dependency where a project references itself. This is invalid because it would create an infinite compilation loop. TypeScript project references allow you to structure large codebases into smaller, interdependent projects that can be built independently. Each project has its own tsconfig.json file and can reference other projects. However, a project cannot reference itself because: 1. **Circular dependency**: A project building itself would need to wait for itself to finish building 2. **Infinite recursion**: The compiler would get stuck in an endless loop trying to resolve dependencies 3. **Build system confusion**: Tools like tsc --build wouldn't know where to start This error commonly occurs in: - Monorepos with many interconnected packages - Complex build configurations with nested project structures - Copy-paste errors when setting up project references - Automated tooling that incorrectly generates tsconfig.json files

How to fix "Project 'X' cannot reference itself"

1Check your tsconfig.json references array

Open your tsconfig.json file and examine the "references" array:

json

{
  "compilerOptions": {
    "composite": true,
    "outDir": "./dist"
  },
  "references": [
    {
      "path": "../shared"  // ✓ Correct - references another project
    },
    {
      "path": "."          // ✗ WRONG - references itself!
    },
    {
      "path": "./"         // ✗ WRONG - also references itself
    }
  ]
}

Remove any entries that point to the current directory (".", "./", or the project's own path).

2Verify project boundaries in monorepos

In monorepos, ensure each package has clear boundaries:

json

// packages/app/tsconfig.json
{
  "references": [
    {
      "path": "../shared"  // ✓ References sibling package
    },
    {
      "path": "../utils"   // ✓ References another sibling
    }
    // NO self-reference here
  ]
}

// packages/shared/tsconfig.json
{
  "references": [
    // Can reference other packages, but not itself
    {
      "path": "../utils"   // ✓ OK
    }
  ]
}

Use absolute or relative paths that clearly point to other projects, never to the current one.

3Use path resolution helpers for complex structures

For complex project structures, use helper functions or variables:

json

// Using tsconfig-paths or similar tools
{
  "extends": "../../tsconfig.base.json",
  "references": [
    {
      "path": "<workspaceRoot>/packages/shared"
    },
    {
      "path": "<workspaceRoot>/packages/utils"
    }
  ]
}

// Or with explicit relative paths:
{
  "references": [
    {
      "path": "../../packages/shared"  // Clear relative path
    }
  ]
}

Avoid dynamic path generation that might accidentally resolve to the current project.

4Check for indirect self-references through symlinks

Symlinks can create indirect self-references:

bash

# Check for symlinks in your project
ls -la node_modules/

# If using npm/yarn workspaces, check for linked packages
npm ls --link

# Remove problematic symlinks if found
rm -f node_modules/current-package

Also check package.json for unusual configurations:

json

{
  "name": "my-package",
  "dependencies": {
    "my-package": "file:."  // ✗ Self-reference in dependencies!
  }
}

Fix by removing self-dependencies.

5Validate with tsc --build --verbose

Use TypeScript's build mode with verbose output to debug:

bash

# Run build with verbose output
npx tsc --build --verbose

# Or for specific tsconfig
npx tsc --project tsconfig.json --build --verbose

# Output will show:
# Project 'packages/app' references:
#   - packages/shared
#   - packages/app  <-- This is the problem!

The verbose output clearly shows which projects reference which others, making self-references obvious.

6Clean and rebuild the project

After fixing the references, clean and rebuild:

bash

# Clean build outputs
npx tsc --build --clean

# Or manually remove output directories
rm -rf dist
rm -rf build
rm -rf .tsbuildinfo

# Rebuild from scratch
npx tsc --build

# For incremental builds
npx tsc --build --incremental

If using a monorepo tool:

bash

# With npm workspaces
npm run build --workspaces

# With yarn workspaces
yarn workspaces foreach run build

# With pnpm
pnpm -r run build

How to fix Project 'X' cannot reference itself in TypeScript

What this error means

Typical symptoms

Common causes

How to fix "Project 'X' cannot reference itself"

Advanced notes

Related errors

Official resources & further reading