You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<!---Recommended: Removal all the comments in this template before you sign-off or merge to master.--->
13
+
# Deploy server-rendered Next.js websites on Azure Static Web Apps
18
14
19
-
# Tutorial: Deploy server-rendered Next.js websites on App Service Static Apps
15
+
In this tutorial, you learn to deploy a [Next.js](https://nextjs.org) generated static website to [Azure Static Web Apps](overview.md). To begin, you learn to set up, configure, and deploy a Next.js app. During this process, you also learn to deal with common challenges often faced when generating static pages with Next.js
20
16
21
-
<!---Required:
22
-
Starts with "Tutorial: "
23
-
Make the first word following "Tutorial:" a verb.
24
-
--->
17
+
## Prerequisites
25
18
26
-
Introductory paragraph.
19
+
- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/).
20
+
- A GitHub account. [Create an account for free](https://github.com/join).
21
+
-[Node.js](https://nodejs.org) installed.
27
22
28
-
<!---Required:
29
-
Lead with a light intro that describes, in customer-friendly language,
30
-
what the customer will learn, or do, or accomplish. Answer the
31
-
fundamental "why would I want to do this?" question.
32
-
--->
23
+
## Set up a Next.js app
33
24
34
-
In this tutorial, you learn how to:
25
+
Rather than using the Next.js CLI to create an app, you can use a starter repository that includes an existing Next.js app. This repository features a Next.js app with dynamic routes, which highlights a common deployment issue. Dynamic routes need an extra deployment configuration which you will learn more about in a moment.
35
26
36
-
> [!div class="checklist"]
37
-
> * All tutorials include a list summarizing the steps to completion
38
-
> * Each of these bullet points align to a key H2
39
-
> * Use these green checkboxes in a tutorial
40
-
<!---Required:
41
-
The outline of the tutorial should be included in the beginning and at
42
-
the end of every tutorial. These will align to the **procedural** H2
43
-
headings for the activity. You do not need to include all H2 headings.
44
-
Leave out the prerequisites, clean-up resources and next steps--->
27
+
To begin, create a new repository under your GitHub account from a template repository.
45
28
46
-
If you don't have a <service> subscription, create a free trial account...
47
-
<!--- Required, if a free trial account exists
48
-
Because tutorials are intended to help new customers use the product or
49
-
service to complete a top task, include a link to a free trial before the
50
-
first H2, if one exists. You can find listed examples in
When you build a Next.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.
66
+
67
+
1. To configure static routes, create file named _next.config.js_ at the root of your project and add the following code..
68
+
69
+
```javascript
70
+
module.exports = {
71
+
exportTrailingSlash: true,
72
+
exportPathMap: function() {
73
+
return {
74
+
'/': { page: '/' }
75
+
};
76
+
}
77
+
};
78
+
```
79
+
80
+
This configuration maps `/` to the Next.js page that is served for the `/` route, and that is the _pages/index.js_ page file.
81
+
82
+
1. Update the _package.json_'s build script to also generate a static site after building, using the `next export` command. The `export` command generates a static site.
83
+
84
+
```json
85
+
"scripts": {
86
+
"dev": "next dev",
87
+
"build": "next build && next export",
88
+
},
89
+
```
90
+
91
+
Now with this command in place, Static Web Apps will run the `build` script every time you push a commit.
92
+
93
+
1. Generate a static site:
94
+
95
+
```bash
96
+
npm run build
97
+
```
98
+
99
+
The static site is generated and copied into an _out_ folder at the root of your working directory.
100
+
101
+
> [!NOTE]
102
+
> This folder is listed in the _.gitignore_ file because it should be generated by CI/CD when you deploy.
103
+
104
+
## Push your static website to GitHub
105
+
106
+
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.
107
+
108
+
1. Stage all changed files
109
+
```bash
110
+
git add .
111
+
```
112
+
1. Commit all changes
113
+
```bash
114
+
git commit -m "Update build config"
115
+
```
116
+
117
+
1. Push your changes to GitHub.
118
+
119
+
```bash
120
+
git push origin master
121
+
```
141
122
142
-
or a code block for Azure PowerShell:
123
+
## Deploy your static website
143
124
144
-
```azurepowershell-interactive
145
-
New-AzureRmContainerGroup -ResourceGroupName myResourceGroup -Name mycontainer -Image microsoft/iis:nanoserver -OsType Windows -IpAddressType Public
125
+
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.
126
+
127
+
### Create a static app
128
+
129
+
1. Navigate to the [Azure portal](https://portal.azure.com).
130
+
1. Click **Create a Resource** then search for **Static Web Apps** and select the matching result.
131
+
132
+
133
+
1. Select a subscription from the *Subscription* drop-down list or use the default value.
134
+
1. Click the **New** link below the *Resource group* drop-down. In *New resource group name*, type **mystaticsite** and click **OK**
135
+
1. 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`.
136
+
1. In the *Region* drop-down, choose a region closest to you.
137
+
1. Select **Free** from the SKU drop-down.
138
+
139
+
140
+
:::image type="content" source="media/deploy-nextjs/create-static-web-app.png" alt-text="Create Static Web App":::
141
+
142
+
### Add a GitHub repository
143
+
144
+
The new Static Web Apps account needs access to the repository with your Next.js app so it can automatically deploy commits.
145
+
146
+
1. Click the **Sign in with GitHub button**
147
+
1. Select the **Organization** under which you created the repo for your Next.js project, which may be your GitHub username.
148
+
1. Find and select the name of the repository you created earlier.
149
+
1. Choose **master** as the branch from the *Branch* drop-down.
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.
156
+
157
+
1. Click on the **Build** tab to configure the static output folder.
2. Type **out** in the *App artifact location* text box.
162
+
163
+
### Review and create
164
+
165
+
1. Click the **Review + Create** button to verify the details are all correct.
166
+
1. Click **Create** to start the creation of the resource and also provision a GitHub Action for deployment.
167
+
1. Once the deployment is completed, click **Go to resource**
168
+
1. On the _Overview_ window, click the *URL* link to open your deployed application.
169
+
170
+
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.
171
+
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.
172
+
173
+
You can check the status of the Actions workflows by navigating to the Actions for your repository:
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.
182
+
183
+
Return to the terminal and run the following command `git pull origin master`.
184
+
185
+
## Configure dynamic routes
186
+
187
+
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.
188
+
189
+
:::image type="content" source="media/deploy-nextjs/404-in-production.png" alt-text="404 on dynamic routes":::
190
+
191
+
The reason for this error is because Next.js only generated the home page based on the application configuration.
192
+
193
+
## Generate static pages from dynamic routes
148
194
149
-
## Clean up resources
195
+
1. Update the _next.config.js_ file so that Next.js uses a list of all available data to generate static pages for each framework/library:
150
196
151
-
If you're not going to continue to use this application, delete
152
-
<resources> with the following steps:
197
+
```javascript
198
+
const data = require('./utils/projectsData');
153
199
154
-
1. From the left-hand menu...
155
-
2. ...click Delete, type...and then click Delete
200
+
module.exports = {
201
+
exportTrailingSlash: true,
202
+
exportPathMap: async function () {
203
+
const { projects } = data;
204
+
const paths = {
205
+
'/': { page: '/' },
206
+
};
207
+
208
+
projects.forEach((project) => {
209
+
paths[`/project/${project.slug}`] = {
210
+
page: '/project/[path]',
211
+
query: { path: project.slug },
212
+
};
213
+
});
214
+
215
+
return paths;
216
+
},
217
+
};
218
+
```
156
219
157
-
<!---Required:
158
-
To avoid any costs associated with following the tutorial procedure, a
159
-
Clean up resources (H2) should come just before Next steps (H2)
160
-
--->
220
+
> [!NOTE]
221
+
> The `exportPathMap` function 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.
161
222
162
-
## Next steps
223
+
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.
163
224
164
-
<!-- Uncomment this block and add the appropriate link
225
+
226
+
:::image type="content" source="media/deploy-nextjs/404-in-production-fixed.png" alt-text="404 on dynamic routes fixed":::
0 commit comments