wiki/prds/netlify-deploy-fix.md

Netlify Deployment Fix

Solution

Add these to your project to fix Netlify builds with Convex:

netlify.toml:

[build]
  command = "npm ci --include=dev && npx convex deploy --cmd 'npm run build'"
  publish = "dist"

[build.environment]
  NODE_VERSION = "20"

package.json build script:

"build": "npx vite build"

Required devDependency:

npm install --save-dev @types/node

---

What went wrong

Four separate issues caused sequential build failures on Netlify.

Issue 1: vite package not found during config load

Error:

npm warn exec The following package was not found and will be installed: vite@7.2.7
failed to load config from /opt/build/repo/vite.config.ts
Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'vite'

Cause: The build script used npx vite build. When npx couldn't find vite locally, it tried downloading the latest version (7.2.7) but failed to resolve the import in vite.config.ts.

Initial fix attempt: Changed build script from npx vite build to vite build to use the locally installed version.

Issue 2: vite command not in PATH

Error:

> vite build
sh: 1: vite: not found

Cause: When npx convex deploy runs npm run build in a subprocess, the node_modules/.bin directory isn't in PATH. The vite command couldn't be found even though the package was installed.

Fix: Changed build script back to npx vite build. npx explicitly resolves binaries from node_modules/.bin.

Issue 3: devDependencies not installed

Error:

sh: 1: vite: not found

Cause: npm ci was running, but NODE_ENV=production was set in netlify.toml:

[context.production.environment]
  NODE_ENV = "production"

With NODE_ENV=production, npm skips devDependencies by default. vite is a devDependency, so it wasn't installed.

Fix: Changed the build command from npm ci to npm ci --include=dev:

command = "npm ci --include=dev && npx convex deploy --cmd 'npm run build'"

The --include=dev flag forces npm to install devDependencies regardless of NODE_ENV.

Issue 4: TypeScript cannot find process.env

Error:

convex/http.ts:9:18 - error TS2580: Cannot find name 'process'.
Do you need to install type definitions for node?
Try `npm i --save-dev @types/node`.

Cause: The Convex HTTP endpoints use process.env.SITE_URL for configuration. TypeScript needs @types/node to recognize Node.js globals like process.

Fix: Added @types/node to devDependencies:

npm install --save-dev @types/node

---

Timeline of fixes

Attempt	Error	Fix applied
1	Cannot find package 'vite'	Changed npx vite build to vite build
2	vite: not found	Changed back to npx vite build
3	vite: not found	Added --include=dev to npm ci
4	Cannot find name 'process'	Added @types/node

---

Why this happens

Netlify's build environment sets NODE_ENV=production for production deploys. This is standard behavior, but it conflicts with projects that need devDependencies (like vite, typescript, etc.) during the build step.

The Convex deploy command runs your build script in a subprocess. That subprocess inherits the environment but not necessarily the PATH modifications that would normally make node_modules/.bin executables available.

---

Checklist for Convex + Netlify deployments

• @types/node in devDependencies (for process.env types)
• Build script uses npx prefix for local binaries
• npm ci --include=dev in netlify.toml build command
• CONVEX_DEPLOY_KEY set in Netlify environment variables
• Node version specified in [build.environment]

---

Final working configuration

netlify.toml:

[build]
  command = "npm ci --include=dev && npx convex deploy --cmd 'npm run build'"
  publish = "dist"

[build.environment]
  NODE_VERSION = "20"

[context.production.environment]
  NODE_ENV = "production"

[context.deploy-preview.environment]
  NODE_ENV = "development"

package.json:

{
  "scripts": {
    "build": "npx vite build"
  },
  "devDependencies": {
    "@types/node": "^25.0.2",
    "vite": "^5.1.4"
  }
}

---

References

• Convex Netlify Hosting Docs
• Netlify Build Environment Variables
• npm ci documentation