How To Fix Deploy a Next.js App To Vercel Actions

Deploying a Next.js app to Vercel is often straightforward, but occasionally, you may run into some issues during the deployment process. One of the most common errors developers face is a dependency conflict error. If you’ve encountered this error, you’re not alone.

I’ll guide you through understanding and fixing a typical deployment issue that can arise when deploying your Next.js app to Vercel, especially involving dependency conflicts.

Let’s break down the error you’re facing and how to resolve it:

The Error

When I attempted to deploy my Next.js app, I encountered the following error message in the logs:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR!
npm ERR! While resolving: @wagmi/core@2.6.3
npm ERR! Found: viem@1.19.13
...
npm ERR! Conflicting peer dependency: viem@2.7.6
...

This error occurs due to dependency conflicts. More specifically, it’s because of incompatible versions of two packages: @wagmi/core and viem. Here’s a breakdown of why this happens:

• @wagmi/core expects viem@2.x as a peer dependency (i.e., it needs version 2 or higher of the viem package).
• My project was using viem@1.19.13.
• Because @wagmi/core cannot work with viem@1.x (which is what I had installed), npm throws the ERESOLVE error when it cannot reconcile the two.

How to Fix the Error

Now that we know what’s happening, let’s go over how we can fix the issue and get our app successfully deployed to Vercel.

Upgrade viem to Version 2.x

The simplest solution here is to upgrade viem to the version required by @wagmi/core. You can do this by running the following command in your project directory:

npm install viem@^2.0.0

This will update viem to a version that is compatible with @wagmi/core. After doing this, the conflict should be resolved, and your dependencies will be aligned.

Use --force or --legacy-peer-deps

If upgrading viem isn’t an option, or if you want to bypass the peer dependency resolution (not recommended unless absolutely necessary), you can run the following command:

npm install --legacy-peer-deps

This flag tells npm to ignore the peer dependency conflict and proceed with the installation. However, while this may fix the immediate issue, it’s important to be aware that it could lead to other potential issues down the road since incompatible versions of packages may lead to bugs or unexpected behavior.

Manually Adjust Your package.json

If you prefer to manage your dependencies more carefully, you can manually adjust the package.json file to ensure that both @wagmi/core and viem are using compatible versions. For instance, you could update the package.json file to match:

"dependencies": {
  "viem": "2.7.6",
  "@wagmi/core": "2.6.3"
}

Once you’ve made these adjustments, you can run:

npm install

This will install the compatible versions that you’ve specified in package.json.

Clear npm Cache and Reinstall

If the error persists after trying the previous steps, clearing the npm cache might help. To do this, run:

npm cache clean --force
npm install

This will clear npm’s cache and force a fresh installation of your dependencies. Sometimes, a corrupted cache can cause issues that prevent successful installations.

Additional Best Practices for Deployment

Once you’ve resolved the issue and successfully deployed your app to Vercel, consider the following best practices for managing dependencies and future deployments:

Install Specific Version of Dependencies

Locking the versions of your dependencies can help avoid conflicts in the future. Update your package.json to pin specific versions for your critical dependencies:

"dependencies": {
  "viem": "2.7.6",
  "@wagmi/core": "2.6.3"
}

This way, every time you install your dependencies, you’re guaranteed that the versions will remain consistent.

Add a Custom npm Script for Deployments

To make deployments smoother and more predictable, you can add a custom deployment script to your package.json. For instance:

"scripts": {
  "deploy": "npm install --legacy-peer-deps && vercel"
}

This ensures that npm installs dependencies using the --legacy-peer-deps flag every time you deploy, which can be particularly helpful if you regularly face peer dependency conflicts.

Automate Dependency Checking

It’s a good idea to automate the process of checking for outdated or vulnerable dependencies. You can use tools like npm-check or npm audit to keep your dependencies up to date and resolve any potential issues before they affect your app. For example, you can run:

npm audit

This will check for any known vulnerabilities in your dependencies and suggest ways to resolve them.

Final Thoughts

Dealing with dependency conflicts can be frustrating, but they’re a common part of working with JavaScript and tools like Next.js. By upgrading packages, using the --legacy-peer-deps flag, and ensuring your package.json is properly configured, you can resolve these issues and move forward with your deployment.

To make the deployment process smoother, remember to lock dependencies, use custom npm scripts for consistent environments, and automate dependency management. By following these practices, you’ll save time in future deployments and maintain a stable environment for your app.