Nuxt/docs/1.getting-started/10.deployment.md

325 lines
10 KiB
Markdown
Raw Normal View History

---
title: 'Deployment'
description: Learn how to deploy your Nuxt application to any hosting provider.
navigation.icon: i-ph-cloud-duotone
---
A Nuxt application can be deployed on a Node.js server, pre-rendered for static hosting, or deployed to serverless or edge (CDN) environments.
::callout
If you are looking for a list of cloud providers that support Nuxt 3, see the [Hosting providers](#hosting-providers) section.
::
## Node.js Server
Discover the Node.js server preset with Nitro to deploy on any Node hosting.
- **Default output format** if none is specified or auto-detected <br>
- Loads only the required chunks to render the request for optimal cold start timing <br>
- Useful for deploying Nuxt apps to any Node.js hosting
### Entry Point
When running `nuxt build` with the Node server preset, the result will be an entry point that launches a ready-to-run Node server.
```bash [Terminal]
node .output/server/index.mjs
```
This will launch your production Nuxt server that listens on port 3000 by default.
It respects the following runtime environment variables:
- `NITRO_PORT` or `PORT` (defaults to `3000`)
- `NITRO_HOST` or `HOST` (defaults to `'0.0.0.0'`)
- `NITRO_SSL_CERT` and `NITRO_SSL_KEY` - if both are present, this will launch the server in HTTPS mode. In the vast majority of cases, this should not be used other than for testing, and the Nitro server should be run behind a reverse proxy like nginx or Cloudflare which terminates SSL.
### PM2
To use `pm2`, use an `ecosystem.config.js`:
```js [ecosystem.config.js]
module.exports = {
apps: [
{
name: 'NuxtAppName',
port: '3000',
exec_mode: 'cluster',
instances: 'max',
script: './.output/server/index.mjs'
}
]
}
```
### Cluster Mode
You can use `NITRO_PRESET=node_cluster` in order to leverage multi-process performance using Node.js [cluster](https://nodejs.org/dist/latest/docs/api/cluster.html) module.
By default, the workload gets distributed to the workers with the round robin strategy.
### Learn More
:read-more{to="https://nitro.unjs.io/deploy/node" title="the Nitro documentation for node-server preset"}
## Static Hosting
There are two ways to deploy a Nuxt application to any static hosting services:
- Static site generation (SSG) with `ssr: true` pre-renders routes of your application at build time. (This is the default behavior when running `nuxi generate`.) It will also generate `/200.html` and `/404.html` single-page app fallback pages, which can render dynamic routes or 404 errors on the client (though you may need to configure this on your static host).
- Alternatively, you can prerender your site with `ssr: false` (static single-page app). This will produce HTML pages with an empty `<div id="__nuxt"></div>` where your Vue app would normally be rendered. You will lose many SEO benefits of prerendering your site, so it is suggested instead to use [`<ClientOnly>`](/docs/api/components/client-only) to wrap the portions of your site that cannot be server rendered (if any).
### Crawl-based Pre-rendering
Use the [`nuxi generate` command](/docs/api/commands/generate) to build and pre-render your application using the [Nitro](/docs/guide/concepts/server-engine) crawler. This command is similar to `nuxt build` with the `nitro.static` option set to `true`, or running `nuxt build --prerender`.
```bash [Terminal]
npx nuxi generate
```
That's it! You can now deploy the `.output/public` directory to any static hosting service or preview it locally with `npx serve .output/public`.
Working of the Nitro crawler:
1. Load the HTML of your application's root route (`/`), any non-dynamic pages in your `~/pages` directory, and any other routes in the `nitro.prerender.routes` array.
2. Save the HTML and `payload.json` to the `~/.output/public/` directory to be served statically.
3. Find all anchor tags (`<a href="...">`) in the HTML to navigate to other routes.
4. Repeat steps 1-3 for each anchor tag found until there are no more anchor tags to crawl.
This is important to understand since pages that are not linked to a discoverable page can't be pre-rendered automatically.
::read-more{to="/docs/api/commands/generate#nuxi-generate"}
Read more about the `nuxi generate` command.
::
### Selective Pre-rendering
You can manually specify routes that [Nitro](/docs/guide/concepts/server-engine) will fetch and pre-render during the build or ignore routes that you don't want to pre-render like `/dynamic` in the `nuxt.config` file:
```ts [nuxt.config.ts]
defineNuxtConfig({
nitro: {
prerender: {
routes: ['/user/1', '/user/2']
ignore: ['/dynamic']
}
}
})
```
You can combine this with the `crawLinks` option to pre-render a set of routes that the crawler can't discover like your `/sitemap.xml` or `/robots.txt`:
```ts [nuxt.config.ts]
defineNuxtConfig({
nitro: {
prerender: {
crawlLinks: true,
routes: ['/sitemap.xml', '/robots.txt']
}
}
})
```
Setting `nitro.prerender` to `true` is similar to `nitro.prerender.crawlLinks` to `true`.
::read-more{to="https://nitro.unjs.io/config#prerender"}
Read more about pre-rendering in the Nitro documentation.
::
### Client-side Only Rendering
If you don't want to pre-render your routes, another way of using static hosting is to set the `ssr` property to `false` in the `nuxt.config` file. The `nuxi generate` command will then output an `.output/public/index.html` entrypoint and JavaScript bundles like a classic client-side Vue.js application.
```ts [nuxt.config.ts]
defineNuxtConfig({
ssr: false
})
```
## Hosting Providers
Nuxt 3 can be deployed to several cloud providers with a minimal amount of configuration:
::card-group
::card
---
title: AWS
icon: i-simple-icons-amazonaws
to: https://nitro.unjs.io/deploy/providers/aws
target: _blank
ui.icon.base: 'text-black dark:text-white'
---
::
::card
---
title: Azure
icon: i-simple-icons-microsoftazure
to: https://nitro.unjs.io/deploy/providers/azure
target: _blank
ui.icon.base: 'text-black dark:text-white'
---
::
::card
---
title: Cleavr
icon: i-ph-cloud-duotone
to: https://nitro.unjs.io/deploy/providers/cleavr
target: _blank
ui.icon.base: 'text-black dark:text-white'
---
::
::card
---
title: Deno
icon: i-simple-icons-deno
to: https://nitro.unjs.io/deploy/providers/deno
target: _blank
ui.icon.base: 'text-black dark:text-white'
---
::
::card
---
title: CloudFlare
icon: i-simple-icons-cloudflare
to: https://nitro.unjs.io/deploy/providers/cloudflare
target: _blank
ui.icon.base: 'text-black dark:text-white'
---
::
::card
---
title: DigitalOcean
icon: i-simple-icons-digitalocean
to: https://nitro.unjs.io/deploy/providers/digitalocean
target: _blank
ui.icon.base: 'text-black dark:text-white'
---
::
::card
---
title: Edgio
icon: i-ph-cloud-duotone
to: https://nitro.unjs.io/deploy/providers/edgio
target: _blank
ui.icon.base: 'text-black dark:text-white'
---
::
::card
---
title: Firebase
icon: i-simple-icons-firebase
to: https://nitro.unjs.io/deploy/providers/firebase
target: _blank
ui.icon.base: 'text-black dark:text-white'
---
::
::card
---
title: Flightcontrol
icon: i-ph-cloud-duotone
to: https://nitro.unjs.io/deploy/providers/flightcontrol
target: _blank
ui.icon.base: 'text-black dark:text-white'
---
::
::card
---
title: GitHub Pages
icon: i-simple-icons-github
to: https://nitro.unjs.io/deploy/providers/github-pages
target: _blank
ui.icon.base: 'text-black dark:text-white'
---
::
::card
---
title: Heroku
icon: i-simple-icons-heroku
to: https://nitro.unjs.io/deploy/providers/heroku
target: _blank
ui.icon.base: 'text-black dark:text-white'
---
::
::card
---
title: Lagon
icon: i-ph-cloud-duotone
to: https://nitro.unjs.io/deploy/providers/lagon
target: _blank
ui.icon.base: 'text-black dark:text-white'
---
::
::card
---
title: Netlify
icon: i-simple-icons-netlify
to: https://nitro.unjs.io/deploy/providers/netlify
target: _blank
ui.icon.base: 'text-black dark:text-white'
---
::
::card
---
title: Render
icon: i-simple-icons-render
to: https://nitro.unjs.io/deploy/providers/render
target: _blank
ui.icon.base: 'text-black dark:text-white'
---
::
::card
---
title: Stormkit
icon: i-ph-cloud-duotone
to: https://nitro.unjs.io/deploy/providers/stormkit
target: _blank
ui.icon.base: 'text-black dark:text-white'
---
::
::card
---
title: Vercel
icon: i-simple-icons-vercel
to: https://nitro.unjs.io/deploy/providers/vercel
target: _blank
ui.icon.base: 'text-black dark:text-white'
---
::
::
## Presets
In addition to Node.js servers and static hosting services, a Nuxt 3 project can be deployed with several well-tested presets and minimal amount of configuration.
You can explicitly set the desired preset in the [`nuxt.config`](/docs/guide/directory-structure/nuxt.config) file:
```js [nuxt.config.ts]
export default {
nitro: {
preset: 'node-server'
}
}
```
... or use the `NITRO_PRESET` environment variable when running `nuxt build`:
```bash [Terminal]
NITRO_PRESET=node-server nuxt build
```
🔎 Check [the Nitro deployment](https://nitro.unjs.io/deploy) for all possible deployment presets and providers.
2023-04-25 12:38:10 +00:00
## CDN Proxy
In most cases, Nuxt can work with third-party content that is not generated or created by Nuxt itself. But sometimes such content can cause problems, especially Cloudflare's "Minification and Security Options".
Accordingly, you should make sure that the following options are unchecked / disabled in Cloudflare. Otherwise, unnecessary re-rendering or hydration errors could impact your production application.
1. Speed > Optimization > Auto Minify: Uncheck JavaScript, CSS and HTML
2. Speed > Optimization > Disable "Rocket Loader™"
3. Speed > Optimization > Disable "Mirage"
4. Scrape Shield > Disable "Email Address Obfuscation"
5. Scrape Shield > Disable "Server-side Excludes"
With these settings, you can be sure that Cloudflare won't inject scripts into your Nuxt application that may cause unwanted side effects.