From 9fc65e485e1bd2803d483981bea6fb09c35efebf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Chopin?= Date: Mon, 11 Oct 2021 19:18:38 +0200 Subject: [PATCH] chore(docs): improve deployment section (#720) --- .../2.directory-structure/15.nuxt.config.md | 2 +- docs/content/3.docs/3.deployment/1.azure.md | 2 +- .../3.docs/3.deployment/2.cloudflare.md | 4 +- .../content/3.docs/3.deployment/3.firebase.md | 26 ++++++++--- docs/content/3.docs/3.deployment/4.netlify.md | 4 +- docs/content/3.docs/3.deployment/5.pm2.md | 2 +- docs/content/3.docs/3.deployment/6.vercel.md | 4 +- .../content/3.docs/3.deployment/99.presets.md | 16 +++---- .../3.docs/3.deployment/99.presets/custom.md | 20 ++++++--- .../3.docs/3.deployment/99.presets/lambda.md | 28 +++++++++++- .../3.docs/3.deployment/99.presets/node.md | 45 +++++++++++++++---- .../3.docs/3.deployment/99.presets/server.md | 24 ++++++---- .../3.deployment/99.presets/service-worker.md | 41 ++++++++++++++--- 13 files changed, 163 insertions(+), 55 deletions(-) diff --git a/docs/content/3.docs/2.directory-structure/15.nuxt.config.md b/docs/content/3.docs/2.directory-structure/15.nuxt.config.md index e3e1af4c28..fd95b99193 100644 --- a/docs/content/3.docs/2.directory-structure/15.nuxt.config.md +++ b/docs/content/3.docs/2.directory-structure/15.nuxt.config.md @@ -14,7 +14,7 @@ export default { } ``` -Learn more about all the different [config properties](/docs/config) +Learn more about all the different [config properties](/docs/directory-structure/nuxt.config) diff --git a/docs/content/3.docs/3.deployment/1.azure.md b/docs/content/3.docs/3.deployment/1.azure.md index b7fdff3eb7..317f7dcc41 100644 --- a/docs/content/3.docs/3.deployment/1.azure.md +++ b/docs/content/3.docs/3.deployment/1.azure.md @@ -4,7 +4,7 @@ icon: LogoAzure # Azure -Learn how to deploy Nuxt to Azure Static Web Apps or Azure Functions. +How to deploy Nuxt to Azure Static Web Apps or Azure Functions. ## Azure Functions diff --git a/docs/content/3.docs/3.deployment/2.cloudflare.md b/docs/content/3.docs/3.deployment/2.cloudflare.md index aaf403d78b..9ffcacd084 100644 --- a/docs/content/3.docs/3.deployment/2.cloudflare.md +++ b/docs/content/3.docs/3.deployment/2.cloudflare.md @@ -7,8 +7,8 @@ icon: LogoCloudFlare How to deploy Nuxt to Cloudflare Workers. ::list -- Support for serverless SSR build -- Zero millisecond cold start with edge rendering +- Support for Workers build output +- Zero millisecond cold start with edge-side rendering - Minimal configuration required :: diff --git a/docs/content/3.docs/3.deployment/3.firebase.md b/docs/content/3.docs/3.deployment/3.firebase.md index 495e66a0ed..fe0711bd3f 100644 --- a/docs/content/3.docs/3.deployment/3.firebase.md +++ b/docs/content/3.docs/3.deployment/3.firebase.md @@ -11,10 +11,9 @@ How to deploy Nuxt to Firebase Hosting. - Minimal configuration required :: - ## Setup -Nitro supports Firebase Hosting with Cloud Functions out of the box. +Nitro supports [Firebase Hosting](https://firebase.google.com/docs/hosting) with Cloud Functions out of the box. **Note**: You will need to be on the **Blaze plan** in order to use Nitro with Cloud Functions. @@ -33,18 +32,33 @@ This file should then be committed to version control. You can also create a `.f Then, just add Firebase dependencies to your project: -```bash +::code-group +```bash [Yarn] yarn add --dev firebase-admin firebase-functions firebase-functions-test ``` +```bash [NPM] +npm install -D firebase-admin firebase-functions firebase-functions-test +``` +:: ### Using Firebase CLI You may instead prefer to set up your project with the `firebase` CLI, which will fetch your project ID for you, add required dependencies (see above) and even set up automated deployments via GitHub Actions. -```bash -# Install firebase CLI globally +#### Install firebase CLI globally + +::code-group +```bash [Yarn] yarn global install firebase-tools -# Initialize your firebase project +``` +```bash [NPM] +npm install -g firebase-tools +``` +:: + +#### Initialize your firebase project + +```bash firebase login firebase init hosting ``` diff --git a/docs/content/3.docs/3.deployment/4.netlify.md b/docs/content/3.docs/3.deployment/4.netlify.md index dd7ff5c385..0b60a0a189 100644 --- a/docs/content/3.docs/3.deployment/4.netlify.md +++ b/docs/content/3.docs/3.deployment/4.netlify.md @@ -4,7 +4,7 @@ icon: LogoNetlify # Netlify -How to deploy Nuxt to [Netlify](https://www.netlify.com). +How to deploy Nuxt to Netlify. ::list - Support for serverless SSR build @@ -14,7 +14,7 @@ How to deploy Nuxt to [Netlify](https://www.netlify.com). ## Setup -Nitro will auto-detect that you are in a Netlify environment and build the correct version of your Nuxt server. The only thing you need to do is ensure that you have Netlify set up to build your project (just select the 'Nuxt' preset from the drop-down menu). +Nitro will auto-detect that you are in a [Netlify](https://www.netlify.com) environment and build the correct version of your Nuxt server. The only thing you need to do is ensure that you have Netlify set up to build your project (just select the 'Nuxt' preset from the drop-down menu). ## Deployment diff --git a/docs/content/3.docs/3.deployment/5.pm2.md b/docs/content/3.docs/3.deployment/5.pm2.md index bf8ff4e8ac..f20510aa7c 100644 --- a/docs/content/3.docs/3.deployment/5.pm2.md +++ b/docs/content/3.docs/3.deployment/5.pm2.md @@ -4,7 +4,7 @@ icon: LogoPM2 # PM2 -How to deploy Nuxt to a Node.js hosting. +How to deploy Nuxt to a Node.js hosting using PM2. ::list - Support for ultra-minimal SSR build diff --git a/docs/content/3.docs/3.deployment/6.vercel.md b/docs/content/3.docs/3.deployment/6.vercel.md index 6bceea6a77..517abb2aab 100644 --- a/docs/content/3.docs/3.deployment/6.vercel.md +++ b/docs/content/3.docs/3.deployment/6.vercel.md @@ -4,7 +4,7 @@ icon: LogoVercel # Vercel -Learn how to deploy a Nuxt application to [Vercel](https://vercel.com). +How to deploy Nuxt to Vercel. ::list - Support for serverless build @@ -14,7 +14,7 @@ Learn how to deploy a Nuxt application to [Vercel](https://vercel.com). ## Setup -By default, Vercel will run your `build` script in the `package.json` and automatically detect the built entrypoint within `.vercel_build_output/`. +By default, [Vercel](https://vercel.com) will run your `build` script in the `package.json` and automatically detect the built entrypoint within `.vercel_build_output/`. ## Deployment diff --git a/docs/content/3.docs/3.deployment/99.presets.md b/docs/content/3.docs/3.deployment/99.presets.md index 42b87471f3..2dd14ddaf0 100644 --- a/docs/content/3.docs/3.deployment/99.presets.md +++ b/docs/content/3.docs/3.deployment/99.presets.md @@ -4,13 +4,13 @@ icon: IconPresets # Presets -There are four provided generic presets for Nuxt Nitro that you can use out-of-the-box. +Nuxt has four provided generic presets that you can use out-of-the-box. -1. [Node.js server *(default)*](/deployment/presets/server) -2. [Node.js function](/deployment/presets/node) -3. [Lambda function](/deployment/presets/lambda) -4. [Service worker](/deployment/presets/service-worker) +::list{type=success} +- [Node.js server *(default)*](/docs/deployment/presets/server) +- [Node.js function](/docs/deployment/presets/node) +- [Lambda function](/docs/deployment/presets/lambda) +- [Service worker](/docs/deployment/presets/service-worker) +:: -If you need to [create a custom preset](/deployment/presets/custom), that's possible too. 🚀 - -You may also want to check out the docs for [platform presets that are supported out-of-the-box](/build/platforms). +If you need to [create a custom preset](/docs/deployment/presets/custom), that's possible too. 🚀 diff --git a/docs/content/3.docs/3.deployment/99.presets/custom.md b/docs/content/3.docs/3.deployment/99.presets/custom.md index 359254d224..722c6d4d30 100644 --- a/docs/content/3.docs/3.deployment/99.presets/custom.md +++ b/docs/content/3.docs/3.deployment/99.presets/custom.md @@ -1,25 +1,33 @@ # Custom build preset (advanced) - - Allows full customization - - This is an advanced usage pattern +Get full control of Nuxt Nitro output to deploy on any kind of hosting platform. -### Setup +::list{type=info} +- Allows full customization +- This is an advanced usage pattern +:: + +::alert{icon=IconPresets} +Back to [presets list](/docs/deployment/presets). +:: + +## Setup You can create your own custom build preset. See [the provided presets](https://github.com/nuxt/framework/blob/main/packages/nitro/src/presets) for examples. -#### Inline preset definition +### Inline preset definition You can define everything that a custom preset would configure directly in the Nitro options: ```ts [nuxt.config.js] export default { nitro: { - // + // preset options } } ``` -#### Reusable preset +### Reusable preset You can also define a preset in a separate file (or publish as a separate npm package). diff --git a/docs/content/3.docs/3.deployment/99.presets/lambda.md b/docs/content/3.docs/3.deployment/99.presets/lambda.md index 81516cf797..c594574266 100644 --- a/docs/content/3.docs/3.deployment/99.presets/lambda.md +++ b/docs/content/3.docs/3.deployment/99.presets/lambda.md @@ -1,10 +1,34 @@ # Lambda function - - Compatible with common lambda formats (AWS, Netlify and others) +Discover the Lambda function preset with Nitro to deploy Nuxt to any lambda-compatible serverless platform. + +::alert{icon=IconPresets} +Back to [presets list](/docs/deployment/presets). +:: + +## Usage + +You can use the [Nuxt config](/docs/directory-structure/nuxt.config) to explicity set the preset to use: + +```ts [nuxt.config.js|ts] +export default { + nitro: { + preset: 'lambda' + } +} +``` + +Or directly use the `NITRO_PRESET` environment variable when running `nuxt build`: + +```bash +NITRO_PRESET=lambda npx nuxt build +``` ### Entrypoint -With `{ preset: 'lambda' }` the result will be an entrypoint that exports a handler function that responds to an event and returns a response. This preset is compatible with [AWS Lambda](https://docs.aws.amazon.com/lex/latest/dg/lambda-input-response-format.html) and [Netlify Functions](https://docs.netlify.com/functions/build-with-javascript). +When running `nuxt build` with the Lambda preset, the result will be an entrypoint that exports a handler function that responds to an event and returns a response. + +This entrypoint is compatible with [AWS Lambda](https://docs.aws.amazon.com/lex/latest/dg/lambda-input-response-format.html) and [Netlify Functions](https://docs.netlify.com/functions/build-with-javascript). It can be used programmatically or as part of a deploy. diff --git a/docs/content/3.docs/3.deployment/99.presets/node.md b/docs/content/3.docs/3.deployment/99.presets/node.md index 5cbaf484d3..4b2a75b101 100644 --- a/docs/content/3.docs/3.deployment/99.presets/node.md +++ b/docs/content/3.docs/3.deployment/99.presets/node.md @@ -1,19 +1,46 @@ # Node.js function - - Compatible with many Node.js servers - - Drop-in usage with express or native http server - - Loads only the chunks required to render the request for optimal cold start timing +Discover the Node.js function preset with Nitro to attach Nuxt as a middleware to any Node.js server. -### Entrypoint +::list +- Compatible with many Node.js servers +- Drop-in usage with express or native http server +- Loads only the chunks required to render the request for optimal cold start timing +:: -With `{ preset: 'node' }` the result will be an entrypoint exporting a function with the familiar `(req, res) => {}` signature used in [express](https://expressjs.com/), [h3](https://github.com/nuxt-contrib/h3), etc. +::alert{icon=IconPresets} +Back to [presets list](/docs/deployment/presets). +:: -**Warning** +## Usage + +You can use the [Nuxt config](/docs/directory-structure/nuxt.config) to explicity set the preset to use: + +```ts [nuxt.config.js|ts] +export default { + nitro: { + preset: 'node' + } +} +``` + +Or directly use the `NITRO_PRESET` environment variable when running `nuxt build`: + +```bash +NITRO_PRESET=node npx nuxt build +``` + +## Entrypoint + +When running `nuxt build` with the Node preset, the result will be an entrypoint exporting a function with the familiar `(req, res) => {}` signature used in [express](https://expressjs.com/), [h3](https://github.com/unjs/h3), etc. + +::alert{type=warning} It is not recommended to use this preset directly, and particularly not with a 3rd-party server. +:: -### Example +## Example -#### Express middleware +### Express middleware ```ts import express from 'express' @@ -25,7 +52,7 @@ app.use(handler) app.listen(3000) ``` -#### Node server +### Node server ```ts import { createServer } from 'http' diff --git a/docs/content/3.docs/3.deployment/99.presets/server.md b/docs/content/3.docs/3.deployment/99.presets/server.md index 46a8590185..f916505a08 100644 --- a/docs/content/3.docs/3.deployment/99.presets/server.md +++ b/docs/content/3.docs/3.deployment/99.presets/server.md @@ -1,12 +1,20 @@ # Node.js server -:ok_hand: **Default preset** if none is specified or auto-detected
-:rocket: Loads only the required chunks to render the request for optimal cold start timing
-:bug: Useful for debugging +Discover the Node.js server preset with Nitro to deploy on any Node hosting. -### Usage +::list +- **Default preset** if none is specified or auto-detected
+- Loads only the required chunks to render the request for optimal cold start timing
+- Useful for debugging +:: -You can use the [Nuxt config](/config) to explicity set the preset to use: +::alert{icon=IconPresets} +Back to [presets list](/docs/deployment/presets). +:: + +## Usage + +You can use the [Nuxt config](/docs/directory-structure/nuxt.config) to explicity set the preset to use: ```ts [nuxt.config.js|ts] export default { @@ -22,7 +30,7 @@ Or directly use the `NITRO_PRESET` environment variable when running `nuxt build NITRO_PRESET=server npx nuxt build ``` -### Entrypoint +## Entrypoint When running `nuxt build` with the Node server preset, the result will be an entrypoint that launches a ready-to-run Node server. @@ -30,14 +38,14 @@ When running `nuxt build` with the Node server preset, the result will be an ent node .output/server/index.mjs ``` -### Example +## Example ```bash $ node .output/server/index.mjs Listening on http://localhost:3000 ``` -### Server timings +## Server timings You can enable the `nitro.timing` option in order to have the logs about the chunk loading and cold start performance. diff --git a/docs/content/3.docs/3.deployment/99.presets/service-worker.md b/docs/content/3.docs/3.deployment/99.presets/service-worker.md index 29149a23a1..2b1148c391 100644 --- a/docs/content/3.docs/3.deployment/99.presets/service-worker.md +++ b/docs/content/3.docs/3.deployment/99.presets/service-worker.md @@ -1,14 +1,41 @@ # Service worker - - Can be used for edge rendering - - No dependency on Node.js - - No Node.js environment and features +Explore the Service worker preset with Nitro to push the boundaries of Nuxt rendering to the edge. -**Warning** +::list +- Can be used for edge-side rendering +- No dependency on Node.js +- No Node.js environment and features +:: + +::alert{icon=IconPresets} +Back to [presets list](/docs/deployment/presets). +:: + +::alert{type=warning} Deployment as service worker has some limitations since SSR code is not running in Node.js environment but pure JavaScript. +:: -### Entrypoint +## Usage -The worker preset produces a service worker that can provide full HTML rendering within a worker context (for example [Cloudflare Workers](/deploy/cloudflare)). It registers appropriate handlers for `fetch`, `install` and `activate`. +You can use the [Nuxt config](/docs/directory-structure/nuxt.config) to explicity set the preset to use: -For more information you can see the [source code](https://github.com/nuxt/nitro/blob/main/src/runtime/entries/service-worker.ts). +```ts [nuxt.config.js|ts] +export default { + nitro: { + preset: 'worker' + } +} +``` + +Or directly use the `NITRO_PRESET` environment variable when running `nuxt build`: + +```bash +NITRO_PRESET=worker npx nuxt build +``` + +## Entrypoint + +The worker preset produces a service worker that can provide full HTML rendering within a worker context (for example [Cloudflare Workers](/docs/deployment/cloudflare)). It registers appropriate handlers for `fetch`, `install` and `activate`. + +For more information you can see the [source code](https://github.com/nuxt/framework/blob/main/packages/nitro/src/runtime/entries/service-worker.ts).