Deploy server-rendered Nuxt.js websites on Azure Static Web Apps Preview

In this tutorial, you learn to deploy a Nuxt.js generated static website to Azure Static Web Apps. To begin, you learn to set up, configure, and deploy a Nuxt.js app. During this process, you also learn to deal with common challenges often faced when generating static pages with Nuxt.js

Prerequisites

Set up a Nuxt.js app

You can set up a new Nuxt.js project using create-nuxt-app. Instead of a new project, in this tutorial you begin by cloning an existing repository. This repository is set up to demonstrate how to deploy a dynamic Nuxt.js app as a static site.

  1. Create a new repository under your GitHub account from a template repository.

  2. Navigate to http://github.com/staticwebdev/nuxtjs-starter/generate

  3. Name the repository nuxtjs-starter

  4. Next, clone the new repo to your machine. Make sure to replace <YOUR_GITHUB_ACCOUNT_NAME> with your account name.

    git clone http://github.com/<YOUR_GITHUB_ACCOUNT_NAME>/nuxtjs-starter
    
  5. Navigate to the newly cloned Nuxt.js app:

    cd nuxtjs-starter
    
  6. Install dependencies:

    npm install
    
  7. Start Nuxt.js app in development:

    npm run dev
    

Navigate to http://localhost:3000 to open the app, where you should see the following website open in your preferred browser:

Start Nuxt.js app

When you click on a framework/library, you should see a details page about the selected item:

Details page

Generate a static website from Nuxt.js build

When you build a Nuxt.js site using npm run build, the app is built as a traditional web app, not a static site. To generate a static site, use the following application configuration.

  1. Update the package.json's build script to only generate a static site using the nuxt generate command:

    "scripts": {
      "dev": "nuxt dev",
      "build": "nuxt generate",
    },
    

    Now with this command in place, Static Web Apps will run the build script every time you push a commit.

  2. Generate a static site:

    npm run build
    

    Nuxt.js will generate the static site and copy it into a dist folder at the root of your working directory.

    Note

    This folder is listed in the .gitignore file because it should be generated by CI/CD when you deploy.

Push your static website to GitHub

Azure Static Web Apps deploys your app from a GitHub repository and keeps doing so for every pushed commit to a designated branch. Use the following commands sync your changes to GitHub.

  1. Stage all changed files:

    git add .
    
  2. Commit all changes

    git commit -m "Update build config"
    
  3. Push your changes to GitHub.

    git push origin master
    

Deploy your static website

The following steps show how to link the app you just pushed to GitHub to Azure Static Web Apps. Once in Azure, you can deploy the application to a production environment.

Create an Azure Static Web Apps Preview resource

  1. Navigate to the Azure portal

  2. Click Create a Resource

  3. Search for Static Web Apps

  4. Click Static Web Apps (Preview)

  5. Click Create

  6. Select a subscription from the Subscription drop-down list or use the default value.

  7. Click the New link below the Resource group drop-down. In New resource group name, type mystaticsite and click OK

  8. Provide a globally unique name for your app in the Name text box. Valid characters include a-z, A-Z, 0-9, and -. This value is used as the URL prefix for your static app in the format of https://<APP_NAME>.azurestaticapps.net.

  9. In the Region drop-down, choose a region closest to you.

  10. Select Free from the SKU drop-down.

    Create Static Web App

Add a GitHub repository

The new Static Web Apps account needs access to the repository with your Nuxt.js app so it can automatically deploy commits.

  1. Click the Sign in with GitHub button

  2. Select the Organization under which you created the repo for your Nuxt.js project, which may be your GitHub username.

  3. Find and select the name of the repository you created earlier.

  4. Choose master as the branch from the Branch drop-down.

    Connect GitHub

Configure the build process

Azure Static Web Apps is built to automatically carry out common tasks like installing npm modules and running npm run build during each deployment. There are, however, a few settings like the application source folder and the build destination folder that you need to configure manually.

  1. Click on the Build tab to configure the static output folder.

    Build tab

  2. Type dist in the App artifact location text box.

Review and create

  1. Click the Review + Create button to verify the details are all correct.
  2. Click Create to start the creation of the resource and also provision a GitHub Action for deployment.
  3. Once the deployment is completed, click Go to resource
  4. On the Overview window, click the URL link to open your deployed application.

If the website does note immediately load, then the background GitHub Actions workflow is still running. Once the workflow is complete you can then click refresh the browser to view your web app.

You can check the status of the Actions workflows by navigating to the Actions for your repository:

https://github.com/<YOUR_GITHUB_USERNAME>/nuxtjs-starter/actions

Sync changes

When you created the app, Azure Static Web Apps created a GitHub Actions workflow file in your repository. You need to bring this file down to your local repository so your git history is synchronized.

Return to the terminal and run the following command git pull origin master.

Configure dynamic routes

Navigate to the newly-deployed site and click on one of the framework or library logos. Instead of getting a details page, you get a 404 error page.

404 on dynamic routes

The reason for this is, Nuxt.js generated the static site, it only did so for the home page. Nuxt.js can generate equivalent static .html files for every .vue pages file, but there's an exception.

If the page is a dynamic page, for example _id.vue, it won't have enough information to generate a static HTML from such dynamic page. You'll have to explicitly provide the possible paths for the dynamic routes.

Generate static pages from dynamic routes

  1. Update the nuxt.config.js file so that Nuxt.js uses a list of all available data to generate static pages for each framework/library:

      import { projects } from "./utils/projectsData";
    
      export default {
        mode: "universal",
    
        //...truncated
    
        generate: {
          async routes() {
            const paths = [];
    
            projects.forEach(project => {
              paths.push(`/project/${project.slug}`);
            });
    
            return paths;
          }
        }
      };
    

    Note

    routes is an async function, so you can make a request to an API in this function and use the returned list to generate the paths.

  2. Push the new changes to your GitHub repository and wait for a few minutes while GitHub Actions builds your site again. After the build is complete, the 404 error disappears.

    404 on dynamic routes fixed