Issue: Duplicate Lexical Installations Causing instanceof Failures

Problem

When using @lexical/headless with lexical in a monorepo, you may encounter cryptic errors like:

Node LexicalNode does not implement .getType().
    at formatDevErrorMessage (/node_modules/lexical/Lexical.dev.mjs:20:9)

Root Cause

This occurs when two separate copies of lexical are installed:

• Your project's lexical (e.g., v0.34) at node_modules/lexical
• A nested lexical (e.g., v0.35) at node_modules/@lexical/headless/node_modules/lexical

The headless editor performs instanceof LexicalNode checks in isAbstractNodeClass() during getStaticNodeConfig(). Since your custom nodes extend LexicalNode from the root installation, but the check uses LexicalNode from the nested installation, JavaScript treats them as different classes. This causes isAbstract() to incorrectly return false.

How to Identify This Issue

Run this command to check for duplicate installations:

npm ls lexical or yarn why lexical

If you see multiple versions or nested installations, you have this problem.

Solution

Step 1: Align Versions

Before installing @lexical/headless, ensure your lexical version matches:

# Check latest versions

npm view lexical version
npm view @lexical/headless version

# Install matching versions

npm install lexical@latest
npm install @lexical/headless@latest

Step 2: Verify package.json

Ensure both packages have identical version numbers:

{
  "dependencies": {
    "lexical": "0.35.0",
    "@lexical/headless": "0.35.0"
  }
}

Step 3: Clean Installation

If issues persist, force a clean installation:

# Remove nested lexical if it exists

rm -rf node_modules/@lexical/headless/node_modules/lexical

# Or do a full reinstall

rm -rf node_modules package-lock.json
npm install

Step 4: Verify Fix

Confirm only one lexical installation exists:
# Should show a flat structure with no duplicates

npm ls lexical 

Prevention for Monorepo Users

Add a resolution to force a single version across your monorepo:

npm (v8.3+):

{
  "overrides": {
    "lexical": "0.35.0"
  }
}```

**yarn:**

{
"resolutions": {
"lexical": "0.35.0"
}
}`
``

pnpm:

{
  "pnpm": {
    "overrides": {
      "lexical": "0.35.0"
    }
  }
}

For Package Maintainers

• Consider making lexical a peer dependency in @lexical/headless to prevent automatic nested installations
• make version mismatches more visible during installation or runtime

This issue is particularly challenging to debug because the error messages don't indicate a version mismatch - they appear as runtime type checking failures.