I'm running a locally hosted convex server and with node actions. When running npx convex dev, it requires Node.js v18. I already installed that on windows using nvm, but it can't seem to find it. I don't want to downgrade to v18, and the docs said it's possible not to have to set the entire project to use v18. How do I just configure the convex server to point to Node v18?
#Localhost Convex Node v18
lethal apex
wooden vaultBOT
Hi @lethal apex. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
You're correct that Convex requires Node.js v18 specifically for running Node.js actions (files with the "use node" directive) in local deployments, but you don't need to set your entire project to use Node 18—only the environment that runs those actions needs it.
However, based on the knowledge sources, the Convex CLI currently expects Node 18 to be available on your system PATH when running local deployments with Node actions. The recommended approach is to use a tool like nvm to install Node 18 and ensure that when you run npx convex dev, Node 18 is the active version in your shell. This does not require downgrading your whole project, just making sure that the convex CLI process itself is using Node 18.
From the docs:
Running Node.js actions (actions defined in files with "use node;") requires having Node.js 18 installed, since this is the version of Node.js used in production when Node.js actions run in AWS Lambda functions. To resolve this you can install and set up nvm and then install Node.js version 18. You don't need to use Node.js 18 for the rest of your project.
Local Deployments Limitations
So, to run Convex with Node 18 for local deployments:
- Install Node 18 using nvm (which you've done).
- Before running npx convex dev, switch your shell to Node 18:
nvm use 18 - Run npx convex dev in that shell.
You can continue to use a different Node version for your main project by switching back with nvm after stopping the Convex process.
Currently, there is no documented way to configure the Convex CLI to use a specific Node binary for actions independently of your shell's active Node version. If you want to avoid switching manually, you could use a shell script or a tool like direnv to automatically set the Node version when you enter your project directory.
If you need to run your frontend or other tooling with a different Node version, you can open a separate terminal window with your preferred Node version active.
If you have further issues with nvm on Windows, make sure you're using nvm-windows and that your PATH is updated correctly.
If you were hoping for a way to configure the Convex CLI to point to a specific Node binary for actions (without switching your shell), the knowledge sources do not mention such a feature at this time. If this is a blocker, you may want to provide feedback to the Convex team or follow updates in their Discord or documentation for future improvements.