Deploy a Nuxt app (Vue 3, Nitro)

Prerequisites

• A Nuxt 3 or newer project (as created by npm create nuxt@latest) with a committed lockfile.
• The standard scripts: "build": "nuxt build" and "postinstall": "nuxt prepare".

How Deployxa detects Nuxt

A nuxt dependency selects the Nuxt preset on Node.js 20.

Required config: a start command

Projects generated by create nuxt have no start script. Add one that runs the built Nitro server, or set the service's start command to the same thing:

{
  "scripts": {
    "build": "nuxt build",
    "dev": "nuxt dev",
    "generate": "nuxt generate",
    "preview": "nuxt preview",
    "postinstall": "nuxt prepare",
    "start": "node .output/server/index.mjs"
  }
}

The default Nitro preset (node-server) reads PORT (or NITRO_PORT) and HOST (or NITRO_HOST). Set HOST=0.0.0.0 and PORT=3000 as environment variables and Internal Port to 3000.

Static generation instead

If every page can be prerendered, run nuxt generate as the build command and serve .output/public as the output directory. No server process is needed, but server routes are not available.

Environment variables and runtime config

Declare config in nuxt.config.ts and override it at runtime with NUXT_-prefixed variables:

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    databaseUrl: '',                 // NUXT_DATABASE_URL
    public: { apiBase: '/api' },     // NUXT_PUBLIC_API_BASE
  },
});

// server/api/hello.get.ts
export default defineEventHandler(() => {
  const config = useRuntimeConfig();
  return { apiBase: config.public.apiBase };
});

Databases

In the wizard's Configure step, set Database to PostgreSQL. The connection string is injected into the app as DATABASE_URL, so nothing needs to be committed. Choose SQLite only for small apps: it lives on a persistent volume and has no server.

Read process.env.DATABASE_URL directly in server routes, or map it to runtime config by setting NUXT_DATABASE_URL to the same connection string. Keep database clients in server/ so they never reach the browser bundle.

Deploy

From the dashboard

1. 1
   Source

   Open Dashboard → Projects → New project (/dashboard/projects/new). Pick the GitHub repository and branch, or upload a .zip archive of the project.

2. 2
   Configure

   Leave the framework preset on Auto-detect or choose Nuxt. Check the fields under advanced settings:

   • Build command: npm run build
   • Output directory: .output
   • Root directory: ./, or the sub-folder that holds the app in a monorepo
3. 3
   Environment

   Add your variables in the table, or paste a whole .env file into the Bulk / .env tab.

4. 4
   Deploy

   Start the deploy and watch the build log. When the release passes its health check it is served over HTTPS on its Deployxa URL.

5. 5
   Confirm the start command and port

   Open the project's Environment Canvas tab and select the web service. Set Start Command to node .output/server/index.mjs. Set Internal Port to 3000 so it matches the port your app listens on. Save and redeploy if you changed anything.

From the CLI

$ npm install -g @deployxa/cli
$ deployxa login
$ cd my-app
$ deployxa link            # pick an existing project, or skip: deploy creates one
$ deployxa env set HOST 0.0.0.0
$ deployxa deploy
$ deployxa logs --live     # stream build and runtime logs
$ deployxa open            # open the live URL

If the folder is not linked, deployxa deploy creates a project named after the folder and links it (the link is saved in .deployxa/config.json). Later runs deploy the linked project. deployxa status shows the latest deployment and deployxa rollback previous returns to the release before it.

Starting fresh? deployxa create nuxt scaffolds a minimal Nuxt starter you can deploy straight away.

Custom domain

Go to Dashboard → Domains, choose Connect a domain you already own and pick this project. Deployxa then shows the DNS records to create at your DNS provider:

DNS changes can take several minutes to propagate; use Retry verification once they have. A Let's Encrypt certificate is issued after the domain verifies. From a linked folder you can do the same with the CLI:

$ deployxa domains add app.example.com
$ deployxa dns             # Waiting → Verified → SSL Active
$ deployxa domains list

Common errors and fixes

Start with deployxa logs --live (or the deployment's log view in the dashboard): the build log shows dependency and compile failures, the runtime log shows crashes and bind errors. See also Troubleshooting.