diff --git a/docs/1.getting-started/10.deployment.md b/docs/1.getting-started/10.deployment.md index 0713165789..672d1c5f65 100644 --- a/docs/1.getting-started/10.deployment.md +++ b/docs/1.getting-started/10.deployment.md @@ -81,52 +81,61 @@ There are two ways to deploy a Nuxt application to any static hosting services: ### Crawl-based Pre-rendering -Use the [`nuxi generate` command](/docs/api/commands/generate) to build your application. For every page, Nuxt uses a crawler to generate a corresponding HTML and payload files. The built files will be generated in the `.output/public` directory. +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 npx nuxi generate ``` -You can enable crawl-based pre-rendering when using `nuxt build` in the `nuxt.config` file: +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`. -```ts [nuxt.config.ts|js] -defineNuxtConfig({ - nitro: { - prerender: { - crawlLinks: true - } - } -}) -``` +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 (``) 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. + +::alert{type=info} +Read more about the [`nuxi generate` command](/docs/api/commands/generate#nuxi-generate). +:: ### Selective Pre-rendering -You can manually specify routes that [Nitro](/docs/guide/concepts/server-engine) will fetch and pre-render during the build. +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|js] defineNuxtConfig({ nitro: { prerender: { routes: ['/user/1', '/user/2'] + ignore: ['/dynamic'] } } }) ``` -When using this option with `nuxi build`, static payloads won't be generated by default at build time. For now, selective payload generation is under an experimental flag. +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|js] defineNuxtConfig({ - /* The /dynamic route won't be crawled */ nitro: { - prerender: { crawlLinks: true, ignore: ['/dynamic'] } - }, - experimental: { - payloadExtraction: true + prerender: { + crawlLinks: true, + routes: ['/sitemap.xml', '/robots.txt'] + } } }) ``` +Setting `nitro.prerender` to `true` is similar to `nitro.prerender.crawlLinks` to `true`. + +::alert{type=info} +Read more about [pre-rendering](https://nitro.unjs.io/config#prerender) 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. diff --git a/docs/3.api/5.commands/generate.md b/docs/3.api/5.commands/generate.md index 596dbc7262..744fbbdc36 100644 --- a/docs/3.api/5.commands/generate.md +++ b/docs/3.api/5.commands/generate.md @@ -15,3 +15,7 @@ Option | Default | Description -------------------------|-----------------|------------------ `rootDir` | `.` | The root directory of the application to generate `--dotenv` | `.` | Point to another `.env` file to load, **relative** to the root directory. + +::alert{type=info} +Read more about [pre-rendering and static hosting](/docs/1.getting-started/10.deployment.md#static-hosting). +::