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
Read more about [file-based plugin installation](https://docs.netlify.com/configure-builds/build-plugins/#file-based-installation) in our docs.
81
74
82
-
## CLI Usage
75
+
## Docs
83
76
84
-
If you'd like to build and deploy your project using the [Netlify CLI](https://docs.netlify.com/cli/get-started/), we recommend this workflow to manage git tracking plugin-generated files:
85
-
86
-
1. Make sure all your project's files are committed before running a build with the CLI
87
-
2. Run any number of builds and deploys freely (i.e. `netlify build`, `netlify deploy --build`, `netlify deploy --prod`)
88
-
3. Run `git stash --include-unstaged` to easily ignore plugin-generated files
89
-
90
-
Plugin-generated files will output into either (a) the default functions and publish directories (`netlify/functions` and `.`, respectively) or (b) whichever custom functions and publish directories you configure. See below for custom directory configuration. It's important to note that, in both cases (a) and (b), the CLI may mix your project's source code and plugin-generated files; this is why we recommend committing all project source files before running CLI builds.
91
-
92
-
**Debugging CLI builds:**
93
-
- If you're seeing a `{FILE_NAME} already exists` error running a CLI build, this may be because your `node_modules` got purged between builds or because of lingering unstashed files from outdated builds. To resolve, you need to manually remove any plugin-generated files from your project directory.
94
-
95
-
We're looking to improve the CLI experience to avoid this manual cleanup and git management! Feel free to open an issue to report feedback on the CLI experience.
96
-
97
-
## Custom Netlify Functions
98
-
99
-
This plugin creates one Netlify Function for each Next.js page that requires one.
100
-
To use custom Netlify Functions in addition to what the plugin generates, add a path to your functions folder in `netlify.toml`:
101
-
102
-
```toml
103
-
[build]
104
-
command = "npm run build"
105
-
functions = "my_functions_dir"
106
-
107
-
[[plugins]]
108
-
package = "@netlify/plugin-nextjs"
109
-
```
110
-
111
-
Read more about [Netlify Functions](https://docs.netlify.com/functions/overview/) in our docs.
112
-
113
-
## Publish Directory
114
-
115
-
Similarly, you can customize your publish directory in your `netlify.toml` file:
116
-
117
-
```toml
118
-
[build]
119
-
command = "npm run build"
120
-
functions = "my_functions_dir"
121
-
publish = "my_publish_dir"
122
-
123
-
[[plugins]]
124
-
package = "@netlify/plugin-nextjs"
125
-
```
126
-
127
-
Read more about [Netlify's build settings](https://docs.netlify.com/configure-builds/get-started/#basic-build-settings) in our docs.
128
-
129
-
## Image Handling
130
-
131
-
The plugin includes a function to generate images for `next/image`. The images are resized on the fly, so the first request will have a short delay. However because the function uses [On-Demand Builders](https://docs.netlify.com/configure-builds/on-demand-builders/), any subsequent requests for that image are served from the edge cache and are super-fast.
132
-
133
-
By default, images are returned in the same format as the source image if they are in JPEG, PNG, WebP or AVIF format. If you are only targeting modern browsers and want to live life on the edge, you can [set the environment variable](https://docs.netlify.com/configure-builds/environment-variables/)`FORCE_WEBP_OUTPUT` to `"true"`, and it will return all images in WebP format. This will often lead to significant improvements in file size. However you should not use this if you need to support older browsers, as `next/image` does not support picture tag source fallback and images will appear broken. Check [browser support](https://caniuse.com/webp) to see if you are happy to do this.
134
-
135
-
If you want to use remote images in `next/image`, you will need to add the image domains to an allow list. Setting them in `images.domains` in `next.config.js` is not supported: instead you should set the environment variable `NEXT_IMAGE_ALLOWED_DOMAINS` to a comma-separated list of domains, e.g. `NEXT_IMAGE_ALLOWED_DOMAINS="placekitten.com,unsplash.com"`.
136
-
137
-
## Custom Netlify Redirects
138
-
139
-
You can define custom redirects in a `_redirects` file.
140
-
The precedence of these rules are:
141
-
142
-
-`_redirects`
143
-
-`next-on-netlify` redirects
144
-
145
-
Read more about [Netlify redirects](https://docs.netlify.com/routing/redirects/) in our docs.
146
-
147
-
## Local Files in Runtime
148
-
149
-
A common requirement for Next.js projects is to require local files in Next.js pages (see [markdown issue](https://github.com/netlify/netlify-plugin-nextjs/issues/153) and [i18next issue](https://github.com/netlify/netlify-plugin-nextjs/issues/223) as examples).
150
-
151
-
In this case, you can configure your netlify.toml to make sure these files are included in the function runtime environment. This is necessary for pages that use fallback: true, SSR, preview mode, etc. For example:
152
-
153
-
```toml
154
-
[build]
155
-
command = "npm run build"
156
-
157
-
[functions]
158
-
# Includes all Markdown files inside the "files/" directory.
159
-
included_files = ["files/*.md"]
160
-
```
161
-
162
-
Read more about functions configuration and `included_files` in our [docs](https://docs.netlify.com/configure-builds/file-based-configuration/#functions).
163
-
164
-
## FAQ
165
-
166
-
**Q: What can I do if my builds fail suddenly from a broken plugin release or plugin dependency?**
167
-
168
-
A: Check out the plugin's [releases](https://github.com/netlify/netlify-plugin-nextjs/releases). You can manually install `npm install --save @netlify/[email protected]` at the last working version.
169
-
Once a new working release is out, you can uninstall the plugin at this locked version (`npm uninstall --save @netlify/plugin-nextjs`), which will re-enable Netlify's build system to use the latest plugin version by default.
170
-
171
-
## Caveats
172
-
173
-
### Versions
174
-
175
-
You can check our `package.json` for supported Node versions.
176
-
177
-
For breaking Next.js releases, all Next.js versions before the breaking release will be locked to the last working plugin version:
178
-
179
-
Next.js < 10.0.6 is locked to plugin version 1.1.3. To use the latest plugin version, upgrade to Next.js >= 10.0.6.
180
-
181
-
### Fallback Pages
182
-
183
-
As of v3.3.0, this plugin uses Netlify's [On-Demand Builders](https://docs.netlify.com/configure-builds/on-demand-builders/) for pages that use `fallback: true` or `fallback: blocking` in getStaticPaths. This means the page is built once and then cached until a future deploy. This is Netlify's first step towards solving the problem ISR originally set out to solve.
184
-
185
-
### Incremental Static Regeneration
186
-
187
-
Using the `revalidate` flag in getStaticProps is not fully supported on Netlify. Currently, this plugin will SSR these pages instead of serving any prerendered/incrementally built HTML. See [this issue](https://github.com/netlify/netlify-plugin-nextjs/issues/151) for more info.
77
+
You can find more documentation on the Essential Next.js plugin [here](https://github.com/netlify/netlify-plugin-nextjs/tree/main/docs).
You can check our `package.json` for supported Node versions.
6
+
7
+
For breaking Next.js releases, all Next.js versions before the breaking release will be locked to the last working plugin version:
8
+
9
+
Next.js < 10.0.6 is locked to plugin version 1.1.3. To use the latest plugin version, upgrade to Next.js >= 10.0.6.
10
+
11
+
### Fallback Pages
12
+
13
+
As of v3.3.0, this plugin uses Netlify's [On-Demand Builders](https://docs.netlify.com/configure-builds/on-demand-builders/) for pages that use `fallback: true` or `fallback: blocking` in getStaticPaths. This means the page is built once and then cached until a future deploy. This is Netlify's first step towards solving the problem ISR originally set out to solve.
14
+
15
+
### Incremental Static Regeneration
16
+
17
+
Using the `revalidate` flag in getStaticProps is not fully supported on Netlify. Currently, this plugin will SSR these pages instead of serving any prerendered/incrementally built HTML. See [this issue](https://github.com/netlify/netlify-plugin-nextjs/issues/151) for more info.
If you'd like to build and deploy your project using the [Netlify CLI](https://docs.netlify.com/cli/get-started/), we recommend this workflow to manage git tracking plugin-generated files:
4
+
5
+
1. Make sure all your project's files are committed before running a build with the CLI
6
+
2. Run any number of builds and deploys freely (i.e. `netlify build`, `netlify deploy --build`, `netlify deploy --prod`)
7
+
3. Run `git stash --include-unstaged` to easily ignore plugin-generated files
8
+
9
+
Plugin-generated files will output into either (a) the default functions and publish directories (`netlify/functions` and `.`, respectively) or (b) whichever custom functions and publish directories you configure. See below for custom directory configuration. It's important to note that, in both cases (a) and (b), the CLI may mix your project's source code and plugin-generated files; this is why we recommend committing all project source files before running CLI builds.
10
+
11
+
**Debugging CLI builds:**
12
+
- If you're seeing a `{FILE_NAME} already exists` error running a CLI build, this may be because your `node_modules` got purged between builds or because of lingering unstashed files from outdated builds. To resolve, you need to manually remove any plugin-generated files from your project directory.
13
+
14
+
We're looking to improve the CLI experience to avoid this manual cleanup and git management! Feel free to open an issue to report feedback on the CLI experience.
**Q: What can I do if my builds fail suddenly from a broken plugin release or plugin dependency?**
4
+
5
+
A: Check out the plugin's [releases](https://github.com/netlify/netlify-plugin-nextjs/releases). You can manually install `npm install --save @netlify/[email protected]` at the last working version.
6
+
Once a new working release is out, you can uninstall the plugin at this locked version (`npm uninstall --save @netlify/plugin-nextjs`), which will re-enable Netlify's build system to use the latest plugin version by default.
The plugin includes a function to generate images for `next/image`. The images are resized on the fly, so the first request will have a short delay. However because the function uses [On-Demand Builders](https://docs.netlify.com/configure-builds/on-demand-builders/), any subsequent requests for that image are served from the edge cache and are super-fast.
4
+
5
+
By default, images are returned in the same format as the source image if they are in JPEG, PNG, WebP or AVIF format. If you are only targeting modern browsers and want to live life on the edge, you can [set the environment variable](https://docs.netlify.com/configure-builds/environment-variables/)`FORCE_WEBP_OUTPUT` to `"true"`, and it will return all images in WebP format. This will often lead to significant improvements in file size. However you should not use this if you need to support older browsers, as `next/image` does not support picture tag source fallback and images will appear broken. Check [browser support](https://caniuse.com/webp) to see if you are happy to do this.
6
+
7
+
If you want to use remote images in `next/image`, you will need to add the image domains to an allow list. Setting them in `images.domains` in `next.config.js` is not supported: instead you should set the environment variable `NEXT_IMAGE_ALLOWED_DOMAINS` to a comma-separated list of domains, e.g. `NEXT_IMAGE_ALLOWED_DOMAINS="placekitten.com,unsplash.com"`.
A common requirement for Next.js projects is to require local files in Next.js pages (see [markdown issue](https://github.com/netlify/netlify-plugin-nextjs/issues/153) and [i18next issue](https://github.com/netlify/netlify-plugin-nextjs/issues/223) as examples).
4
+
5
+
In this case, you can configure your netlify.toml to make sure these files are included in the function runtime environment. This is necessary for pages that use fallback: true, SSR, preview mode, etc. For example:
6
+
7
+
```toml
8
+
[build]
9
+
command = "npm run build"
10
+
11
+
[functions]
12
+
# Includes all Markdown files inside the "files/" directory.
13
+
included_files = ["files/*.md"]
14
+
```
15
+
16
+
Read more about functions configuration and `included_files` in our [docs](https://docs.netlify.com/configure-builds/file-based-configuration/#functions).
0 commit comments