How Can I Fix Dependency Conflicts During Vercel Deployment for Next.js

When I encountered an error deploying my Next.js project to Vercel, it was a frustrating experience. The error was related to conflicting dependencies in my package.json file, which were causing the deployment to fail even though everything worked fine on my local environment. After a thorough investigation, I discovered that the issue stemmed from a version mismatch between @tiptap/core and @tiptap/extension-font-size.

I’ll walk you through the exact error I faced, explain the underlying cause, and then share the steps I took to resolve the issue and successfully deploy my project to Vercel.

The Problem

The deployment error on Vercel looked like this:

npm error @tiptap/starter-kit@"^2.11.5" from the root project
npm error Could not resolve dependency:
npm error peer @tiptap/core@"^3.0.0-next.3" from @tiptap/extension-font-size@3.0.0-next.3
npm error Conflicting peer dependency: @tiptap/core@3.0.0-next.6

From the error message, it was clear that the root cause of the problem was a dependency conflict between @tiptap/extension-font-size and @tiptap/core. Specifically:

• @tiptap/extension-font-size@3.0.0-next.3 requires @tiptap/core@^3.0.0-next.3.
• However, I had @tiptap/core@3.0.0-next.6 installed, which was causing the conflict since the required version was slightly different.

Interestingly, this didn’t break my local build. I could run npm run build just fine on my local machine, but Vercel was having trouble resolving the peer dependency during deployment. This was due to stricter version matching enforced by npm in the deployment environment.

My Current package.json Setup

Here’s the relevant part of my package.json where the conflict occurred:

{
  "dependencies": {
    "@tiptap/extension-font-family": "^2.11.5",
    "@tiptap/extension-font-size": "^3.0.0-next.3",
    "@tiptap/react": "^2.11.5",
    "@tiptap/starter-kit": "^2.11.5",
    "@tiptap/suggestion": "^2.11.5",
    "@tiptap/extension-image": "^2.11.5",
    "@tiptap/extension-list": "^3.0.0-next.4",
    "next": "15.0.1",
    "react": "^18.2.0"
  }
}

The version of @tiptap/extension-font-size was ^3.0.0-next.3, which was incompatible with the version of @tiptap/core that I had installed, 3.0.0-next.6.

How I Resolved the Issue

Update the Dependencies to Compatible Versions

The first thing I did was to ensure that all Tiptap-related packages were aligned in terms of their versioning. Since @tiptap/extension-font-size was expecting @tiptap/core@^3.0.0-next.3, I updated the version of @tiptap/extension-font-size to match the version of @tiptap/core I was using.

I modified my package.json like so:

"@tiptap/extension-font-size": "^3.0.0-next.6",
"@tiptap/core": "^3.0.0-next.6"

This update ensures that both the extension and core packages are using the same major version, which resolves the peer dependency conflict.

After making this change, I ran:

npm install

This command ensures that the correct versions are installed and should fix the issue locally.

Use the --legacy-peer-deps Flag on Vercel Deployment (Temporary Solution)

If updating the dependencies didn’t resolve the problem, I could use the --legacy-peer-deps flag as a workaround. This flag tells npm to install packages even if there’s a conflict in the peer dependencies.

For Vercel deployment, I can add this option in the deployment script or specify it in my vercel.json (or configure it directly within the Vercel project settings under the build command).

Example:

npm install --legacy-peer-deps

This approach is a quick fix, but it’s not ideal for long-term stability, as it ignores peer dependency conflicts, potentially leading to other issues later on.

Pin Dependency Versions

If I had already tested the project locally and confirmed it worked with the specific versions I was using, I would ensure that all dependencies are pinned to specific versions. This would prevent npm from mistakenly updating packages that are known to be incompatible. For example, instead of using "^3.0.0-next.3", I would specify the exact version like so:

"@tiptap/extension-font-size": "3.0.0-next.6"

This ensures that every install uses the exact version of the package, avoiding future conflicts during deployment.

Check for Additional Errors

Finally, I ran npm audit fix to check if any additional dependency issues or vulnerabilities needed attention. This step is essential for ensuring that all packages are up-to-date and secure.

Final Thoughts

Resolving dependency conflicts can be challenging, especially when a project works locally but fails during deployment on platforms like Vercel. By aligning versions of conflicting packages, using flags like --legacy-peer-deps, and pinning exact versions, you can avoid many common issues. It’s essential to ensure that dependencies are compatible and tested thoroughly before deployment. Regularly checking for vulnerabilities using commands like npm audit fix will also help maintain a stable and secure project. With these steps, I was able to successfully deploy my Next.js project without further issues.