Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 32 ยท Deployment

Building and deploying Nuxt

Build a Nuxt app, understand the .output folder, pick a Nitro preset (Node, static, Vercel, Cloudflare, Docker), set env at runtime and add a health check.

Everything so far ran on your laptop with the dev server, which compiles pages on demand and favors fast feedback over speed. Production is a different job. You build the app once: Nuxt bundles the browser code, Nitro bundles the server, and the result is written to a self-contained folder. Then you run that folder, or upload it to a platform.

What makes Nuxt pleasant here is Nitro, the server engine you met in Server routes and the Nitro engine. Nitro compiles your app for a chosen preset: a plain Node.js server, a folder of static files, a Vercel or Cloudflare function, and more. You write the app once and change the deployment target with one setting.

Real or stand-in? Building and deploying cannot happen on this site, so every command and configuration file below is real but read-only. The three runnable examples are Node.js stand-ins: one decides what a preset would produce, one merges runtime environment variables into a config, and the last is a tiny server with a health-check endpoint that behaves like a container platform would expect.

What a build produces

Bundle Browser code and server code are compiled.
Prerender Routes marked for it become HTML files.
.output One folder holds everything needed to run.

Build once, run it as many times as you like.

1 / 2

The two build commands

There are two commands, and the difference matters:

Terminal
# read-only
npx nuxt build      # server + browser build for a running server
npx nuxt generate   # same, but prerenders every route into static files
npx nuxt preview    # serve the production build locally to test it

nuxt build creates a server. Pages are rendered on the server for each request (or from a cache), exactly as configured in your rendering modes and routeRules. nuxt generate crawls your app from its entry routes, renders each page to HTML at build time, and writes static files. It is the right choice only when every page can be known ahead of time.

Always run nuxt preview before you deploy. It runs the real production output on your machine, which catches problems that the dev server hides, for example a variable that exists in .env but is missing in production.

What is inside .output

After nuxt build you get a folder named .output (the .nuxt folder is only the dev and build workspace; never deploy it). For the default Node preset it looks like this:

TEXT
.output/
  nitro.json            # which preset was used, version, date
  public/               # files served directly: hashed JS/CSS in _nuxt/, favicon, images
  server/
    index.mjs           # the entry point: run this with Node
    chunks/             # your pages, API routes and middleware, split into chunks
    node_modules/       # only the packages the server really needs, already traced

Two details are worth remembering. First, the server folder carries its own trimmed node_modules, so on the server you do not run npm install: you copy .output and start Node. Second, the files in public/_nuxt/ have content hashes in their names, so you can cache them for a year, and a new build simply uses new names.

Start the built server with:

Terminal
# read-only
node .output/server/index.mjs
# listens on port 3000 by default; change it with PORT (or NITRO_PORT) and HOST (or NITRO_HOST)
PORT=8080 HOST=0.0.0.0 node .output/server/index.mjs

Nitro presets

A preset tells Nitro what shape of output to produce. You set it in the config or with an environment variable at build time:

TypeScript
// nuxt.config.ts (read-only)
export default defineNuxtConfig({
  nitro: {
    preset: 'node-server', // the default for nuxt build
  },
})
Terminal
# read-only: the same choice from the command line
NITRO_PRESET=cloudflare-pages npx nuxt build

Some presets you will meet most often:

Preset Output Typical home
node-server .output/server/index.mjs VPS, Docker, Kubernetes, any host with Node
static .output/public (what nuxt generate uses) Any static host, S3, a CDN
vercel Vercel Build Output files Vercel
netlify Netlify functions and files Netlify
cloudflare-pages Worker script plus static assets Cloudflare Pages
bun, deno-server A server for those runtimes Hosts that run Bun or Deno

On several platforms (Vercel, Netlify, Cloudflare Pages) Nitro detects the environment during the platform's own build and picks the right preset for you, so you often write no preset line at all. Check your platform's current Nuxt guide for the exact steps, because these integrations change faster than the framework does.

The runtime also matters for your code. A Node preset can use any Node API and a database driver. Edge presets run a smaller runtime: no node:fs, no native modules, short time limits. If you plan to deploy to the edge, check early that your server code and your database client work there (Databases and ORMs).

The first stand-in decides what the output of a project would be. It takes a short description of the app and a preset, and prints what you can host, what needs a server, and what the preset cannot do. The rules are simplified, but they match the mental model you need when choosing a target.

Node.js What does each preset let you deploy?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The output makes the choice concrete. With node-server, prerendered pages are files and /account and the API run live. With static, you still get all pages as files, but the account page and both API routes have nowhere to run, which is why a fully static site needs an external backend for anything dynamic. Always compare this list against your real needs before picking a target.

Environment variables at runtime

The most common deployment bug is about configuration, not code. Remember the rule from Runtime config and environment variables: keys you declare in runtimeConfig can be overridden at runtime by environment variables named NUXT_ plus the key in upper snake case, and public keys use NUXT_PUBLIC_.

TypeScript
// nuxt.config.ts (read-only)
export default defineNuxtConfig({
  runtimeConfig: {
    databaseUrl: '',            // NUXT_DATABASE_URL (server only)
    public: {
      apiBase: '/api',          // NUXT_PUBLIC_API_BASE
    },
  },
})
Terminal
# read-only: production start with real environment variables
NUXT_DATABASE_URL=file:./data/app.db NUXT_PUBLIC_API_BASE=https://api.example.com \
  node .output/server/index.mjs

Two warnings. The override only works for keys that already exist in runtimeConfig: declare every key, even with an empty default, or the variable is ignored. And .env is a development convenience: the built server does not load it for you, so set real variables in your host, in your container settings, or start Node with its own --env-file option if you want a file.

The second stand-in merges environment variables into a default config in the same way. It is not Nuxt's code, but the rule is the same.

Node.js Merge NUXT_ variables into runtime config

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

You can see which variables took effect, and one that was silently ignored because the key was never declared. The last line is the part to remember: only the public object is sent to the browser. The database URL stays on the server.

A health check

A deployed server needs an address that answers "are you alive and able to work?". Load balancers, Docker and Kubernetes poll it, and restart or stop sending traffic when it fails. In Nuxt it is an ordinary server route:

TypeScript
// server/api/health.get.ts (read-only)
export default defineEventHandler(async () => {
  // optionally check something cheap and essential, such as a database ping
  return { status: 'ok', time: new Date().toISOString() }
})

Keep it cheap and public, and never include secrets or version details you would not show a stranger. If it checks the database, return a failing status code with createError({ statusCode: 503 }) when the check fails, so the platform can react.

The third piece of a deploy is a container, for hosts that run Docker. A multi-stage build keeps the final image small, because only .output is copied:

DOCKERFILE
# Dockerfile (read-only)
FROM node:24-slim AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npx nuxt build

FROM node:24-slim
WORKDIR /app
COPY --from=build /app/.output ./.output
ENV PORT=3000 HOST=0.0.0.0
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s \
  CMD node -e "fetch('http://127.0.0.1:3000/api/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
CMD ["node", ".output/server/index.mjs"]

The stand-in below is a small Node server with /api/health, run on a free port and called with fetch. It also handles a termination signal the way a container stop works: finish current requests, then exit. The signal part is described in comments, because a script cannot signal itself safely here.

Node.js A server with a health check

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The first probe returns 503, the second 200. That is the behavior a platform wants: do not send traffic to a server that is still starting. Real Nitro servers handle shutdown signals for you in the Node preset, but knowing the pattern helps when you debug a container that takes too long to stop.

A deployment checklist

  • Run nuxt build and nuxt preview locally, and click through the important pages.
  • Choose the preset that matches where the app will run, and check that your server code works in that runtime.
  • Declare every environment-driven key in runtimeConfig, and set the real variables on the host.
  • Keep secrets out of runtimeConfig.public.
  • Add a health route and point the platform at it.
  • Set cache headers for _nuxt/ assets (immutable) and decide caching for pages with routeRules (Performance and Core Web Vitals).
  • Put a CDN in front of public pages, and purge it when content changes.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What do you run to start a production build with the default Node preset?

    The build writes a self-contained .output folder. Its server entry point is .output/server/index.mjs, and you start it with Node.
  2. 2. What is the difference between nuxt build and nuxt generate?

    nuxt build produces a server that renders on demand, while nuxt generate crawls the app and writes static HTML, which is only enough for sites with no live server routes.
  3. 3. Why might NUXT_PUBLIC_API_BASE have no effect in production?

    Runtime overrides only apply to keys that already exist in runtimeConfig. Declare the key with a default and the variable will override it.
  4. 4. Why does a deployed app usually need a health check route?

    Platforms poll a cheap endpoint such as /api/health and stop sending traffic, or restart the instance, when it fails.

Summary

  • nuxt build creates .output, a self-contained folder. For the Node preset you run node .output/server/index.mjs with no npm install on the server.
  • nuxt generate prerenders every route into static files and suits sites without live server routes.
  • A Nitro preset changes the output shape: Node server, static, Vercel, Netlify, Cloudflare and others. Edge runtimes limit what server code can do.
  • Runtime variables named NUXT_... and NUXT_PUBLIC_... override declared runtimeConfig keys. .env is not read by the built server.
  • Add a cheap /api/health route, and use a multi-stage Dockerfile that copies only .output.
  • Test with nuxt preview before every deploy.

Next: Project: a blog with Nuxt Content style Markdown