Frameworks /

Nuxt on Netlify

Nuxt is an open source, modular framework for building performant sites and applications using Vue.js.

# Key features

These Nuxt features provide key benefits for sites and apps, including ones built and deployed with Netlify.

  • Improved SEO. With the ability to statically generate your site, Nuxt can help to boost search engine optimization for your content.
  • Page routing. Nuxt has a file system-based routing structure. Organizing files and subdirectories within a pages directory automatically results in corresponding routes.
  • Image optimization. The nuxt/image module, backed by Netlify Image CDN, allows you to automatically optimize images for your site.
  • Git-based Headless CMS. The nuxt/content module parses Markdown, JSON, YAML, XML and CSV files within your site.
  • Server-side rendering. Powered by the Nitro server engine, SSR is supported automatically when you use Nuxt 3.

# Netlify integration

Nuxt sites on Netlify can benefit from automatic framework detection and require minimal setup considerations.

Nuxt 3 introduces new rendering options, such as server-side rendering (SSR). SSR is supported when you deploy Nuxt 3 to Netlify, but requires configuration when you use Edge Functions.

For more information, check out the Nuxt Getting Started Guide and Deploy Nuxt to Netlify doc.

# Automatic framework detection

When you link a repository for a project, Netlify tries to detect the framework your site is using.

If your site is built with Nuxt, Netlify provides a suggested build command and publish directory:

  • Nuxt 3: npm run build (assuming your build command is set to nuxt build) and dist
  • Nuxt 2: nuxt generate and dist

If you’re using the CLI to run Netlify Dev for a local development environment, the CLI should work automatically assuming you are using the dev command and port: nuxt and 3000. You can override suggested values or set them in a configuration file instead, but automatic framework detection may help simplify the process of setting up a site on Netlify.

For manual configuration, check out the typical build settings for Nuxt.

# pnpm support

If you’re planning to use pnpm with Nuxt 3, you must set a PNPM_FLAGS environment variable with a value of --shamefully-hoist. This appends an argument to the pnpm install command that Netlify runs. Learn more about using pnpm on Netlify.

# Edge Functions

Edge Functions connect the Netlify platform and workflow with an open runtime standard at the network edge. This enables you to build fast, personalized web experiences with an ecosystem of development tools.

Nuxt supports server-side rendering (SSR), but the use of Edge Functions requires some configuration. When you use Edge Functions, Nitro, the server engine that powers Nuxt, will not auto-detect them and needs a different deployment preset. Learn more in the Nitro documentation.

You can browse a full library of reference examples for different ways to use Edge Functions. For more details, check out the Edge Functions documentation.

# Netlify Image CDN

When deploying your Nuxt applications to Netlify, the Nuxt image module automatically uses Netlify Image CDN to optimize and transform images on demand without impacting build times. Netlify Image CDN also handles content negotiation to use the most efficient image format for the requesting client.

To transform a source image hosted on another domain, you must first configure allowed domains in your netlify.toml file:

  remote_images = ["*", "[bcr]at/.*"]

The remote_images property accepts an array of regex. If your images are in specific subdomains or directories, you can use regex to allow just those subdomains or directories.

Visit the Nuxt Image docs to learn more.

# Deploy a Nuxt site on Netlify

This section demonstrates how to deploy a Nuxt site on Netlify. It covers:

  • Starting a new project using Nuxt
  • Deploying your Nuxt project to Netlify with Netlify CLI

# Start a new project using Nuxt

Before you begin, make sure you have Node.js version 18.14.0 or later installed on your machine.

  1. To get started, create your project from the command line with any of the following package managers:

    npx nuxi@latest init my-project
    pnpm dlx nuxi@latest init my-project
  2. Next, navigate to your project directory and install your dependencies:

    cd my-project
    npm install
    cd my-project
    pnpm install
    cd my-project
    yarn install

    When using pnpm, you must set a PNPM_FLAGS environment variable with a value of --shamefully-hoist.

  3. Start your development server:

    npm run dev -- -o
    pnpm dev -o
    yarn dev -o

From here you can customize your site. You can also create a Git repository for your site to take advantage of continuous deployment.

Avoid 404s for SPAs

If your project is a single page app (SPA) that uses the history pushState method to get clean URLs, you must add a rewrite rule to serve the index.html file no matter what URL the browser requests.

# Deploy your Nuxt project with Netlify CLI

You can deploy your project from the command line using Netlify CLI.

  1. To ensure you have the latest version of Netlify CLI installed, run this command from any directory in your terminal:

    npm install netlify-cli -g
  2. In the directory for your project, run the following command to create a new Netlify site:

    netlify init

Didn’t initialize a Git repository?

When you run netlify init without initializing a Git repository first, the CLI prompts you to connect your local directory to GitHub. Follow the steps in your terminal to link your local directory with a remote repo in order to use continuous deployment for your site.

  1. Follow the prompts to create your site, select a team if necessary, and optionally create a site name. If you already initialized a Git repository, you can authorize your Git provider and set your build command and directory.

  2. If you used continuous deployment, your site is now published! To learn how to manually deploy a site, check out the manual deploy docs.

# More resources