Deploying a Nuxt app to Netlify
Netlify will build a Nuxt app with almost no configuration, and that is the problem: the default works right up until the moment your repository is shaped slightly differently from the one Netlify assumes. This post is about the three settings that actually earn their place, the two environment variables that are load-bearing rather than decorative, and the failure mode that produces a perfectly green deploy of an empty site.
If you want the self-hosted version — systemd, PM2, TLS at a proxy — that is a separate post. This one is about handing the whole thing to Netlify.
Everything below was verified against Nuxt 4.5.2 on Nitro 2.13.4, Node 24, deploying this site from its own netlify.toml.
The base directory is the first thing to get wrong
Netlify looks for a package.json at the root of the repository. This site does not have one: it is two independent packages with separate lockfiles and no workspace tooling, because there is deliberately no root manifest.
With no hint, Netlify either builds the wrong directory or fails before Nuxt starts. One line fixes it:
[build]
base = "nuxt"
command = "npm run build"That base is doing more than pointing at a folder. It is also what makes Netlify skip the build entirely when that directory has not changed — its own diff, not anything you configured.
The whole file
This is the entire deploy configuration, and it is worth reading as a whole because the interesting part is what is missing:
[build]
base = "nuxt"
command = "npm run build"
[build.environment]
NODE_ENV = "production"
NPM_FLAGS = "--include=dev"No publish, no Nitro preset, no ignore command. Netlify auto-detects Nuxt and applies its Nitro preset; and because base is set, the skip-if-unchanged behaviour already exists. Adding a hand-rolled ignore would be a second mechanism that can disagree with the first.
NODE_ENV=production is load-bearing, not decoration
The instinct is that NODE_ENV=production is what the platform sets for you. On Netlify it is not — and in this project it is not cosmetic, because something breaks if it is missing.
Nuxt config blocks keyed by environment name are read by c12, which resolves the environment from process.env.NODE_ENV. A block declared under $production is therefore dropped entirely when NODE_ENV is anything else. Here that block declares the analytics scripts, and a modules:done hook asserts that a private runtime key it depends on actually exists:
Drop the $production block and that key never gets created, so the hook throws and the build fails. That is a deliberate design — the failure is loud instead of shipping a site with analytics silently switched off.
The same variable is what activates the analytics at all. On a build without it you get no error, no warning, and no tags loading.
NPM_FLAGS is the other half of that
Setting NODE_ENV=production has a side effect nobody wants during a build: npm uses it to decide whether to install devDependencies, and it omits them.
This project runs nuxt prepare as a postinstall, and that step needs the TypeScript package to generate .nuxt/. Without the dev dependencies the build dies before Nuxt even starts — which is why the line above it looks unrelated to the one below it:
Where the variables actually live
Four of this site's variables are configured in the Netlify dashboard rather than in the repository: SANITY_PROJECT_ID, SANITY_DATASET, SANITY_API_VERSION and NUXT_SITE_URL.
This is worth internalising because of how it fails. A build missing them is green. The project id falls back to an empty string, the Sanity client is configured with no project, every query returns nothing, and the site deploys successfully with no content and no error anywhere.
So: check the variables before you debug "no content". And after any deploy, curl a real route and read the body — a 200 with the wrong content is still a 200.
The .env trap, restated for this platform
A .env file is not read in a Netlify build. It is not read by nuxt preview either, unless you ask for it. Locally everything works because npm run dev loads it, so the failure only ever appears after deploy.
Keep .env.example tracked and .env ignored, and treat the dashboard as the only source of truth for a deployed build. If a variable is missing in production, it is missing everywhere — the local file is not a fallback.
Marking a token as secret will fail your build
This one cost me a deploy, and the reason is specific enough to be worth writing down.
Nuxt inlines private runtimeConfig into the server bundle at build time. So a value that is only ever read on the server — a read-only viewer token, say — is genuinely server-only, and it never reaches the browser. You can verify that: build with a marker token and grep the output.
It appears in exactly one place, the Nitro server chunk, and not in public/. Good — that is the correct design.
Now mark that variable as "contains secret values" in Netlify. Doing so switches on secret scanning, which scans your build output for the value and fails the build when it finds it. The scanner is doing its job: the token really is sitting in a build artefact.
So you get a choice. Leave the variable unmarked and the build just works, which is reasonable for a low-privilege read-only token on a single-admin site. Or keep the stricter posture — write-only, masked in the UI and logs — and tell the scanner the presence is intentional:
SECRETS_SCAN_OMIT_KEYS = SANITY_VIEWER_TOKENOne more thing to watch: smart detection can flag a high-entropy value on its own, independently of the secret flag. If a deploy fails mentioning smart detection, safelist the value rather than deleting it.
Do not add @netlify/nuxt
It is tempting, because the module is officially named after the platform. It is also unnecessary here, and the reason is worth stating precisely.
Nitro selects the netlify preset because the platform tells it to. The module is a wrapper around @netlify/vite-plugin, which exists to emulate Netlify platform primitives inside `nuxt dev` — Functions, Blobs, the Cache API, edge logic. This site uses none of them: there is no server directory at all.
Its one build-affecting option is explicitly experimental and supports TanStack Start and SolidStart, not Nuxt, and its own README says it is not a full replacement for the Netlify CLI. It is also a very young release with almost no adoption, which is a poor trade for zero functional gain in a repository that deliberately resists dependency drift.
There is one place it could matter later: Image CDN. That would only apply if you abandoned the built-in Sanity image provider for Netlify's — a swap, not an upgrade.
compatibilityDate
One line, and it matters more than it looks. This site sets compatibilityDate = "2025-07-15", comfortably past the 2024-05-07 that Netlify requires for Functions v2, so the server output runs on the current runtime instead of being pinned to a legacy one. Set it too low and you get an old Nitro runtime you did not ask for; leave it unset and the platform guesses.
Verify the file was actually read
On the first deploy, confirm in the build log that NODE_ENV=production appears and that your four dashboard variables are listed. If NODE_ENV is absent from the log, Netlify ignored the root netlify.toml — move it to nuxt/netlify.toml and drop the base line, since the file is now already in the right directory.
A short checklist
Point base at the directory that actually has a package.json.
Set NODE_ENV = "production" — and expect it to matter.
Set NPM_FLAGS = "--include=dev" so the postinstall has its tools.
Keep every real variable in the dashboard, and keep .env out of the build.
If you mark a secret, add SECRETS_SCAN_OMIT_KEYS for any value Nuxt inlines.
After deploying, curl a route and read the body.
References
Netlify build configuration — base, command, NPM_FLAGS
Netlify environment variables and secret scanning
Nuxt deployment documentation
Nitro deployment targets
