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.
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
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.**
Dor Yaloz
SW engineer with 6+ years of experience,
I worked with React/Node/Python
did projects with React+Capacitor.js for ios
Supabase expert
Milan Surelia
Milan Surelia is a Mobile App Developer with 5+ years of experience crafting scalable, cross-platform apps at 7Span and Meticha. At 7Span, he engineers feature-rich Flutter apps with smooth performance and modern UI. As the Co-Founder of Meticha, he builds open-source tools and developer-focused products that solve real-world problems.
Expertise:
💡 Developing cross-platform apps using Flutter, Dart, and Jetpack Compose for Android, iOS, and Web.
🖋️ Sharing insights through technical writing, blogging, and open-source contributions.
🤝 Collaborating closely with designers, PMs, and developers to build seamless mobile experiences.
Notable Achievements:
🎯 Revamped the Vepaar app into Vepaar Store & CRM with a 2x performance boost and smoother UX.
🚀 Launched Compose101 — a Jetpack Compose starter kit to speed up Android development.
🌟 Open source contributions on Github & StackOverflow for Flutter & Dart
🎖️ Worked on improving app performance and user experience with smart solutions.
Milan is always happy to connect, work on new ideas, and explore the latest in technology.
Matt Butler
Software Engineer @ AWS
Matthew Butler
Systems Development Engineer @ Amazon Web Services
Mehdi Ben Haddou
- Founder of Chessigma (1M+ users) & many small projects
- ex Founding Engineer @Uplane (YC F25)
- ex Software Engineer @Amazon and @Booking.com
Costea Adrian
Embedded Engineer specilizing in perception systems. Latest project was a adas camera calibration system.
BurnHavoc
Been around fixing other peoples code for 20 years.
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.