Deploy a Nuxt App

Nuxt (opens in a new tab) is a Vue.js based web framework designed to make it easier to develop high performance, user-centered web applications. It features automatic imports, an extensible module system, file-based routing, multiple rendering modes, and a serverless-friendly server engine called Nitro.

This guide explains how to deploy a Nuxt application to Koyeb using:

1. Git-driven deployment to automatically build and deploy a new version of your application each time a change is detected on your branch.
2. Pre-built containers you can deploy from any public or private registry.

To successfully follow this documentation, you will need to have a Koyeb account (opens in a new tab). You can optionally install the Koyeb CLI if you prefer to follow this guide without leaving the terminal.

You can deploy and preview the Nuxt application from this guide using the Deploy to Koyeb button below.

(opens in a new tab)

You can consult the repository on GitHub (opens in a new tab) to find out more about the example application that this guide uses.

Create the Nuxt app

Get started by creating a minimalistic Nuxt application that we will deploy to Koyeb. You will need Node.js (opens in a new tab) installed on your machine.

To generate a new Nuxt application, run the npx nuxi init command. Include the name you want to use for the new project as its final argument. For this guide, we'll use the name example-nuxt:

npx nuxi init example-nuxt

Nuxt will initialize a new project directory that matches the name you selected. Move into the new directory to view the project files:

cd example-nuxt

If you run tree -a, du -a, or similar directory tree commands, a directory structure similar to this should be present:

.
├── app.vue
├── .gitignore
├── .npmrc
├── nuxt.config.ts
├── package.json
├── public
│   └── favicon.ico
├── README.md
└── tsconfig.json

1 directory, 8 files

Install the project dependencies

Next, install the project's dependencies by typing:

npm install

You may be prompted to select whether you wish to provide telemetry information. Type either y or n and press Enter to proceed.

Run the Nuxt app locally

Now that the dependencies are installed, start the development server by typing:

npm run dev

Nuxt generates files (opens in a new tab) related to your application in the hidden .nuxt directory during development. In your web browser, navigate to http://127.0.0.1:3000 to see the default landing page generated by Nuxt. This shows that the development server is able to serve your project successfully.

Press CTRL-C to stop the development server after verifying.

Back at the command line, open the project's package.json file in your editor. By default, Nuxt doesn't include a script to start the project using a non-developer server, so we will add the appropriate command to make it easier to deploy.

{
  "name": "nuxt-app",
  "private": true,
  "scripts": {
    "build": "nuxt build",
    "dev": "nuxt dev",
    "generate": "nuxt generate",
    "preview": "nuxt preview",
    "start": "node .output/server/index.mjs",
    "postinstall": "nuxt prepare"
  },
  "devDependencies": {
    "@types/node": "^18",
    "nuxt": "^3.4.3"
  }
}

Save and close the file when you are finished.

Push the project to GitHub

Once you've verified that the project runs locally, create a new Git repository to save your work.

Run the following commands to create a new Git repository within the project's root directory, commit the project files, and push changes to GitHub.

git init
git add .
git commit -m "Initial commit"
git remote add origin git@github.com:<YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME>.git
git push -u origin main

Deploy to Koyeb using git-driven deployment

Deploy to Koyeb using a pre-built container

As an alternative to using git-driven deployment, you can deploy a pre-built container from any public or private registry. This can be useful if your application needs specific system dependencies or you need more control over how the build is performed.

To dockerize the Nuxt application, start by adding a file called .dockerignore to the project's root directory. Paste the following contents to limit the files copied to the Docker image:

Dockerfile
.dockerignore
node_modules
npm-debug.log
.nuxt
.output
.git
dist
README.md

Afterwards, create a Dockerfile in your project root directory and copy the content below:

FROM node:18-alpine AS base
 
FROM base AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
 
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build && npm cache clean --force
 
FROM base AS runner
WORKDIR /app
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nuxt
COPY --from=builder /app .
USER nuxt
EXPOSE 3000
ENV PORT 3000
CMD ["npm", "run", "start"]

The Dockerfile above provides the minimum requirements to run the Nuxt application. You can easily extend it depending on your needs.

To build and push the Docker image to a registry and deploy it on Koyeb, refer to the page on deploying pre-built container images.