Deploying a Nuxt app to Netlify

Deploying a Nuxt app to Netlify

·39 min read

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:

ini
[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:

ini
[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:

ini
SECRETS_SCAN_OMIT_KEYS = SANITY_VIEWER_TOKEN

One 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

More Articles

Deploy your Nuxt app to production

In 2020 I wrote a post on deploying a Nuxt app with PM2. A lot of it no longer applies. nuxt start does not exist any more, the config file is nuxt.config.ts instead of nuxt.config.js, and the build output is no longer something you serve with a hand-written process command — it is a self-contained server you run with one line. This post replaces it. If you landed here from a search, use this one and ignore anything about target: "server".

Deploy your Nuxt app using PM2 (outdated)

This post is out of date. Nuxt 4 removed nuxt start, the config file is nuxt.config.ts, and the target: "server" option no longer exists. The pm2 deploy workflow below still exists, but it is no longer how I would set this up. My current replacement: Deploy your Nuxt app to production →

Using Sanity.io with Nuxt 4

This site used to keep its blog posts as Markdown files and read them at build time. It now keeps them in Sanity and queries them at runtime. That migration is mostly plumbing, but a handful of things about it are genuinely counter-intuitive, and each one cost me time, so this post is about those rather than about how to install a module.