NPM Conflicting Peer Dependencies in Windsurf Project
Running npm install in your Windsurf-generated project fails with ERESOLVE peer dependency conflict errors. Cascade added packages that require incompatible versions of shared dependencies, and npm cannot resolve a valid dependency tree.
This is one of the most frustrating issues in Node.js projects because it blocks all progress — you can't install any packages until the conflict is resolved. The error messages are dense and confusing, listing multiple packages and version ranges that seem impossible to untangle.
The problem typically appears after Cascade adds a new package, when upgrading an existing package, or when combining packages that Cascade recommended in different sessions without checking compatibility.
Error Messages You Might See
Common Causes
- React version conflicts — One package requires React 17 while another requires React 18, or a package needs React as a peer dependency but the project uses a different version
- Multiple UI library versions — Cascade installed both an old and new version of the same UI library (e.g., Material UI v4 and v5)
- Outdated packages — Cascade recommended packages with peer dependencies pinned to old versions that conflict with your current stack
- TypeScript version mismatch — Different packages require different TypeScript versions as peer dependencies
- Using --legacy-peer-deps as a band-aid — Previous installs used --legacy-peer-deps to hide conflicts, creating an unstable node_modules that eventually breaks
How to Fix It
- Read the error carefully — npm's ERESOLVE error tells you exactly which packages conflict and what versions they need. Identify the root conflicting dependency
- Check if packages have compatible versions — Often updating one conflicting package to its latest version resolves the peer dependency conflict
- Use npm ls to inspect the tree — Run npm ls [package-name] to see which versions are installed and which packages depend on them
- Remove and reinstall — Delete node_modules and package-lock.json, then run npm install fresh. This often resolves phantom conflicts from corrupted lock files
- Use overrides for stubborn conflicts — Add an "overrides" field in package.json to force a specific version of the conflicting peer dependency
- Avoid --force and --legacy-peer-deps — These flags hide the problem but can cause runtime errors. Only use them as a last resort after understanding the implications
Real developers can help you.
Taufan
I’m a product-focused engineer and tech leader who builds scalable systems and turns ideas into production-ready platforms.
Over the past years, I’ve worked across startups and fast-moving teams, leading backend architecture, improving system reliability, and shipping products used by thousands of users. My strength is not just writing code — but connecting product vision, technical execution, and business impact.
Matthew Butler
Systems Development Engineer @ Amazon Web Services
Antriksh Narang
5 years+ Experienced Dev (Specially in Web Development), can help in python, javascript, react, next.js and full stack web dev technologies.
Anthony Akpan
Developer with 8 years of experience building softwares fro startups
Nam Tran
10 years as fullstack developer
Jen Jacobsen
I’m a Full-Stack Developer with over 10 years of experience building modern web and mobile applications. I enjoy working across the full product lifecycle — turning ideas into real, well-built products that are intuitive for users and scalable for businesses.
I particularly enjoy building mobile apps, modern web platforms, and solving complex technical problems in a way that keeps systems clean, reliable, and easy to maintain.
zipking
I am a technologist and product builder dedicated to creating high-impact solutions at the intersection of AI and specialized markets. Currently, I am focused on PropScan (EstateGuard), an AI-driven SaaS platform tailored for the Japanese real estate industry, and exploring the potential of Archify.
As an INFJ-T, I approach development with a "systems-thinking" mindset—balancing technical precision with a deep understanding of user needs. I particularly enjoy the challenge of architecting Vertical AI SaaS and optimizing Small Language Models (SLMs) to solve specific, real-world business problems. Whether I'm in a CTO-level leadership role or hands-on with the code, I thrive on building tools that turn complex data into actionable value.
Luca Liberati
I work on monoliths and microservices, backends and frontends, manage K8s clusters and love to design apps architecture
Jaime Orts-Caroff
I'm a Senior Android developer, open to work in various fields
Meïr Ankri
Full-stack developer specializing in React / Next.js / Node.js with 6+ years of experience. I've worked across various sectors including automotive (Reezocar/Société Générale), healthcare (Medical Link SaaS), and e-commerce (Glasman). I build web apps end-to-end, from architecture to production, with a focus on scalability, performance, and code quality. I also mentor junior developers and contribute to technical decisions and code reviews.
You don't need to be technical. Just describe what's wrong and a verified developer will handle the rest.
Get HelpFrequently Asked Questions
Is it safe to use --legacy-peer-deps?
It's a temporary workaround, not a fix. --legacy-peer-deps tells npm to ignore peer dependency conflicts, which may cause runtime errors if the packages are truly incompatible. Use it only to unblock yourself while you find a proper resolution.
What are peer dependencies and why do they cause conflicts?
Peer dependencies are packages that a library expects YOU to install (like React for a React component library). Conflicts happen when two libraries expect different versions of the same peer dependency. Only one version can exist in your project.