Skip to content

Commit 7690840

Browse files
v-regandownerv-regandowner
authored
Merge pull request #206048 from anthonychu/nuxt3-tutorial
Update Nuxt tutorial for Nuxt 3 universal rendering
2 parents 4afc1d4 + dead0d7 commit 7690840

File tree

2 files changed

+34
-102
lines changed

2 files changed

+34
-102
lines changed

‎articles/static-web-apps/deploy-nuxtjs.md

Lines changed: 34 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,41 @@
11
---
2-
title: "Tutorial: Deploy static-rendered Nuxt.js websites on Azure Static Web Apps"
3-
description: "Generate and deploy Nuxt.js dynamic sites with Azure Static Web Apps."
2+
title: "Tutorial: Deploy Nuxt sites with universal rendering on Azure Static Web Apps"
3+
description: "Generate and deploy Nuxt 3 sites with universal rendering on Azure Static Web Apps."
44
services: static-web-apps
55
author: craigshoemaker
66
ms.service: static-web-apps
77
ms.topic: tutorial
8-
ms.date: 05/08/2020
8+
ms.date: 09/01/2022
99
ms.author: cshoe
1010
ms.custom: devx-track-js
1111
---
1212

13-
# Deploy static-rendered Nuxt.js websites on Azure Static Web Apps
13+
# Deploy Nuxt 3 sites with universal rendering on Azure Static Web Apps
1414

15-
In this tutorial, you learn to deploy a [Nuxt.js](https://nuxtjs.org) generated static website to [Azure Static Web Apps](overview.md). 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
15+
In this tutorial, you learn to deploy a [Nuxt 3](https://v3.nuxtjs.org/) application to [Azure Static Web Apps](overview.md). Nuxt 3 supports [universal (client-side and server-side) rendering](https://v3.nuxtjs.org/guide/concepts/rendering/#universal-rendering), including server and API routes. Without extra configuration, you can deploy Nuxt 3 apps with universal rendering to Azure Static Web Apps. When the app is built in the Static Web Apps GitHub Action or Azure Pipelines task, Nuxt 3 automatically converts it into static assets and an Azure Functions app that are compatible with Azure Static Web Apps.
1616

1717
## Prerequisites
1818

1919
- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/).
2020
- A GitHub account. [Create an account for free](https://github.com/join).
21-
- [Node.js](https://nodejs.org) installed.
21+
- [Node.js](https://nodejs.org) 16 or later installed.
2222

23-
## Set up a Nuxt.js app
23+
## Set up a Nuxt 3 app
2424

25-
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.
25+
You can set up a new Nuxt project using `npx nuxi init nuxt-app`. Instead of using a new project, this tutorial uses an existing repository set up to demonstrate how to deploy a Nuxt 3 site with universal rendering on Azure Static Web Apps.
2626

27-
1. Create a new repository under your GitHub account from a template repository.
28-
1. Navigate to [http://github.com/staticwebdev/nuxtjs-starter/generate](https://github.com/login?return_to=/staticwebdev/nuxtjs-starter/generate)
29-
1. Name the repository **nuxtjs-starter**.
27+
1. Navigate to [http://github.com/staticwebdev/nuxt-3-starter/generate](https://github.com/login?return_to=/staticwebdev/nuxt-3-starter/generate).
28+
1. Name the repository **nuxt-3-starter**.
3029
1. Next, clone the new repo to your machine. Make sure to replace <YOUR_GITHUB_ACCOUNT_NAME> with your account name.
3130

3231
```bash
33-
git clone http://github.com/<YOUR_GITHUB_ACCOUNT_NAME>/nuxtjs-starter
32+
git clone http://github.com/<YOUR_GITHUB_ACCOUNT_NAME>/nuxt-3-starter
3433
```
3534

3635
1. Navigate to the newly cloned Nuxt.js app:
3736

3837
```bash
39-
cd nuxtjs-starter
38+
cd nuxt-3-starter
4039
```
4140

4241
1. Install dependencies:
@@ -48,46 +47,16 @@ You can set up a new Nuxt.js project using `create-nuxt-app`. Instead of a new p
4847
1. Start Nuxt.js app in development:
4948

5049
```bash
51-
npm run dev
50+
npm run dev -- -o
5251
```
5352

54-
Navigate to `http://localhost:3000` to open the app, where you should see the following website open in your preferred browser:
53+
Navigate to `http://localhost:3000` to open the app, where you should see the following website open in your preferred browser. Select the buttons to invoke server and API routes.
5554

56-
:::image type="content" source="media/deploy-nuxtjs/start-nuxtjs-app.png" alt-text="Start Nuxt.js app":::
55+
:::image type="content" source="media/deploy-nuxtjs/nuxt-3-app.png" alt-text="Start Nuxt.js app":::
5756

58-
When you click on a framework/library, you should see a details page about the selected item:
57+
## Deploy your Nuxt 3 site
5958

60-
:::image type="content" source="media/deploy-nuxtjs/start-nuxtjs-details.png" alt-text="Details page":::
61-
62-
## Generate a static website from Nuxt.js build
63-
64-
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.
65-
66-
1. Update the _package.json_'s build script to only generate a static site using the `nuxt generate` command:
67-
68-
```json
69-
"scripts": {
70-
"dev": "nuxt dev",
71-
"build": "nuxt generate"
72-
},
73-
```
74-
75-
Now with this command in place, Static Web Apps will run the `build` script every time you push a commit.
76-
77-
1. Generate a static site:
78-
79-
```bash
80-
npm run build
81-
```
82-
83-
Nuxt.js will generate the static site and copy it into a _dist_ folder at the root of your working directory.
84-
85-
> [!NOTE]
86-
> This folder is listed in the _.gitignore_ file because it should be generated by CI/CD when you deploy.
87-
88-
## Deploy your static website
89-
90-
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.
59+
The following steps show how to create an Azure Static Web Apps resource and configure it to deploy your app from GitHub.
9160

9261
### Create an Azure Static Web Apps resource
9362

@@ -102,7 +71,7 @@ The following steps show how to link the app you just pushed to GitHub to Azure
10271
| --- | --- |
10372
| _Subscription_ | Your Azure subscription name. |
10473
| _Resource group_ | **my-nuxtjs-group** |
105-
| _Name_ | **my-nuxtjs-app** |
74+
| _Name_ | **my-nuxt3-app** |
10675
| _Plan type_ | **Free** |
10776
| _Region for Azure Functions API and staging environments_ | Select a region closest to you. |
10877
| _Source_ | **GitHub** |
@@ -119,76 +88,39 @@ The following steps show how to link the app you just pushed to GitHub to Azure
11988

12089
1. In the _Build Details_ section, select **Custom** from the _Build Presets_ drop-down and keep the default values.
12190

122-
1. In the _App location_, enter **./** in the box.
123-
1. Leave the _Api location_ box empty.
124-
1. In the _Output location_ box, enter **dist**.
91+
1. In the _App location_, enter **/** in the box.
92+
1. In the _Api location_, enter **.output/server** in the box.
93+
1. In the _Output location_, enter **.output/public** in the box.
12594

12695
### Review and create
12796

128-
1. Select the **Review + Create** button to verify the details are all correct.
97+
1. Select **Review + Create** to verify the details are all correct.
12998

130-
1. Select **Create** to start the creation of the App Service Static Web App and provision a GitHub Actions for deployment.
99+
1. Select **Create** to start the creation of the static web app and provision a GitHub Actions for deployment.
131100

132-
1. Once the deployment completes click, **Go to resource**.
101+
1. Once the deployment completes, select **Go to resource**.
133102

134-
1. On the _Overview_ window, click the *URL* link to open your deployed application.
103+
1. On the _Overview_ window, select the *URL* link to open your deployed application.
135104

136-
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.
105+
If the website does not immediately load, then the background GitHub Actions workflow is still running. Once the workflow is complete you can then refresh the browser to view your web app.
137106

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

140109
```url
141-
https://github.com/<YOUR_GITHUB_USERNAME>/nuxtjs-starter/actions
110+
https://github.com/<YOUR_GITHUB_USERNAME>/nuxt-3-starter/actions
142111
```
143112

144-
### Sync changes
145-
146-
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.
113+
### Synchronize changes
147114

148-
Return to the terminal and run the following command `git pull origin main`.
115+
When you created the app, Azure Static Web Apps created a GitHub Actions workflow file in your repository. Return to the terminal and run the following command to pull the commit containing the new file.
149116

150-
## Configure dynamic routes
151-
152-
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.
153-
154-
:::image type="content" source="media/deploy-nuxtjs/404-in-production.png" alt-text="404 on dynamic routes":::
155-
156-
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.
157-
158-
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.
159-
160-
## Generate static pages from dynamic routes
161-
162-
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:
163-
164-
```javascript
165-
import { projects } from "./utils/projectsData";
166-
167-
export default {
168-
mode: "universal",
169-
170-
//...truncated
171-
172-
generate: {
173-
async routes() {
174-
const paths = [];
175-
176-
projects.forEach(project => {
177-
paths.push(`/project/${project.slug}`);
178-
});
179-
180-
return paths;
181-
}
182-
}
183-
};
184-
```
185-
186-
> [!NOTE]
187-
> `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.
117+
```bash
118+
git pull
119+
```
188120

189-
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.
121+
Make changes to the app by updating the code and pushing it to GitHub. GitHub Actions automatically builds and deploys the app.
190122

191-
:::image type="content" source="media/deploy-nuxtjs/404-in-production-fixed.png" alt-text="404 on dynamic routes fixed":::
123+
For more information, see the Azure Static Web Apps Nuxt 3 deployment preset [documentation](https://v3.nuxtjs.org/guide/deploy/providers/azure/).
192124

193125
> [!div class="nextstepaction"]
194126
> [Set up a custom domain](custom-domain.md)

‎articles/static-web-apps/media/deploy-nuxtjs/nuxt-3-app.png

1.19 MB
Loading

0 commit comments

Comments
 (0)