Windsurf
integration
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
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! Could not resolve dependency: peer react@"^17.0.0" from package@1.0.0
npm ERR! Conflicting peer dependency: react@17.0.2
npm ERR! Fix the upstream dependency conflict
npm WARN overriding peer dependency
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.
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.
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.
Stanislav Prigodich
15+ years building iOS and web apps at startups and enterprise companies. I want to use that experience to help builders ship real products - when something breaks, I'm here to fix it.
Daniel Vázquez
Software Engineer with over 10 years of experience on Startups, Government, big tech industry & consulting.
Costea Adrian
Embedded Engineer specilizing in perception systems. Latest project was a adas camera calibration system.
Caio Rodrigues
I'm a full-stack developer focused on building practical and scalable web applications. My main experience is with **React, TypeScript, and modern frontend architectures**, where I prioritize clean code, component reusability, and maintainable project structures.
I have strong experience working with **dynamic forms, state management (Redux / React Hook Form), and complex data-driven interfaces**. I enjoy solving real-world problems by turning ideas into reliable software that companies can actually use in their daily operations.
Beyond coding, I care about **software quality and architecture**, following best practices for componentization, code organization, and performance optimization.
I'm also comfortable working across the stack when needed, integrating APIs, handling business logic, and helping transform prototypes into production-ready systems.
My goal is always to deliver solutions that are **simple, efficient, and genuinely useful for the people using them.**
Kingsley Omage
Fullstack software engineer passionate about AI Agents, blockchain, LLMs.
Sage Fulcher
Hey I'm Sage! Im a Boston area software engineer who grew up in South Florida. Ive worked at a ton of cool places like a telehealth kidney care startup that took part in a billion dollar merger (Cricket health/Interwell health), a boutique design agency where I got to work on a ton of exciting startups including a photography education app, a collegiate Esports league and more (Philosophie), a data analytics as a service startup in Cambridge (MA) as well as at Phillips and MIT Lincoln Lab where I designed and developed novel network security visualizations and analytics. I've been writing code and furiously devoted to using computers to make people’s lives easier for about 17 years. My degree is in making computers make pretty lights and sounds. Outside of work I love hip hop, the Celtics, professional wrestling, magic the gathering, photography, drumming, and guitars (both making and playing them)
MFox
Full-stack professional senior engineer (15+years). Extensive experience in software development, qa, and IP networking.
prajwalfullstack
Hi Im a full stack developer, a vibe coded MVP to Market ready product, I'm here to help
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.