From a3b523bca367ad7bb1e7e720cb3491e931458114 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Ollivier?= Date: Wed, 20 Apr 2022 19:54:40 +0200 Subject: [PATCH] docs: update deployment section (#4452) Co-authored-by: pooya parsa Co-authored-by: Daniel Roe --- docs/components/atoms/icons/IconCloud.vue | 56 ++++++ .../content/2.guide/1.concepts/3.rendering.md | 2 - docs/content/2.guide/1.concepts/index.md | 1 + .../2.guide/3.directory-structure/2.output.md | 2 +- .../2.guide/3.directory-structure/index.md | 1 + .../content/2.guide/5.deploy/1.node-server.md | 54 +++++ .../2.guide/5.deploy/2.static-hosting.md | 42 ++++ docs/content/2.guide/5.deploy/3.presets.md | 37 ++++ docs/content/2.guide/5.deploy/index.md | 7 + .../content/2.guide/5.deploy/providers/aws.md | 11 ++ .../2.guide/5.deploy/providers/azure.md | 18 ++ .../2.guide/5.deploy/providers/cloudflare.md | 18 ++ .../5.deploy/providers/digitalocean.md | 11 ++ .../2.guide/5.deploy/providers/firebase.md | 15 ++ .../2.guide/5.deploy/providers/heroku.md | 11 ++ .../2.guide/5.deploy/providers/index.md | 3 + .../2.guide/5.deploy/providers/layer0.md | 13 ++ .../providers/netlify.md} | 10 +- .../2.guide/5.deploy/providers/render.md | 11 ++ .../2.guide/5.deploy/providers/stormkit.md | 11 ++ .../providers/vercel.md} | 30 ++- docs/content/2.guide/5.deployment/1.azure.md | 184 ------------------ .../2.guide/5.deployment/2.cloudflare.md | 136 ------------- .../2.guide/5.deployment/3.firebase.md | 114 ----------- docs/content/2.guide/5.deployment/5.pm2.md | 58 ------ .../2.guide/5.deployment/99.presets.md | 17 -- .../2.guide/5.deployment/99.presets/custom.md | 55 ------ .../2.guide/5.deployment/99.presets/lambda.md | 44 ----- .../2.guide/5.deployment/99.presets/node.md | 64 ------ .../2.guide/5.deployment/99.presets/server.md | 80 -------- .../5.deployment/99.presets/service-worker.md | 42 ---- docs/content/2.guide/5.deployment/index.md | 9 - docs/content/2.guide/6.going-further/index.md | 1 + docs/content/3.api/5.commands/generate.md | 11 ++ 34 files changed, 351 insertions(+), 828 deletions(-) create mode 100644 docs/components/atoms/icons/IconCloud.vue create mode 100644 docs/content/2.guide/5.deploy/1.node-server.md create mode 100644 docs/content/2.guide/5.deploy/2.static-hosting.md create mode 100644 docs/content/2.guide/5.deploy/3.presets.md create mode 100644 docs/content/2.guide/5.deploy/index.md create mode 100644 docs/content/2.guide/5.deploy/providers/aws.md create mode 100644 docs/content/2.guide/5.deploy/providers/azure.md create mode 100644 docs/content/2.guide/5.deploy/providers/cloudflare.md create mode 100644 docs/content/2.guide/5.deploy/providers/digitalocean.md create mode 100644 docs/content/2.guide/5.deploy/providers/firebase.md create mode 100644 docs/content/2.guide/5.deploy/providers/heroku.md create mode 100644 docs/content/2.guide/5.deploy/providers/index.md create mode 100644 docs/content/2.guide/5.deploy/providers/layer0.md rename docs/content/2.guide/{5.deployment/4.netlify.md => 5.deploy/providers/netlify.md} (69%) create mode 100644 docs/content/2.guide/5.deploy/providers/render.md create mode 100644 docs/content/2.guide/5.deploy/providers/stormkit.md rename docs/content/2.guide/{5.deployment/6.vercel.md => 5.deploy/providers/vercel.md} (88%) delete mode 100644 docs/content/2.guide/5.deployment/1.azure.md delete mode 100644 docs/content/2.guide/5.deployment/2.cloudflare.md delete mode 100644 docs/content/2.guide/5.deployment/3.firebase.md delete mode 100644 docs/content/2.guide/5.deployment/5.pm2.md delete mode 100644 docs/content/2.guide/5.deployment/99.presets.md delete mode 100644 docs/content/2.guide/5.deployment/99.presets/custom.md delete mode 100644 docs/content/2.guide/5.deployment/99.presets/lambda.md delete mode 100644 docs/content/2.guide/5.deployment/99.presets/node.md delete mode 100644 docs/content/2.guide/5.deployment/99.presets/server.md delete mode 100644 docs/content/2.guide/5.deployment/99.presets/service-worker.md delete mode 100644 docs/content/2.guide/5.deployment/index.md create mode 100644 docs/content/3.api/5.commands/generate.md diff --git a/docs/components/atoms/icons/IconCloud.vue b/docs/components/atoms/icons/IconCloud.vue new file mode 100644 index 0000000000..6af6ac41c6 --- /dev/null +++ b/docs/components/atoms/icons/IconCloud.vue @@ -0,0 +1,56 @@ + diff --git a/docs/content/2.guide/1.concepts/3.rendering.md b/docs/content/2.guide/1.concepts/3.rendering.md index 7b5d9d4945..4e0074b696 100644 --- a/docs/content/2.guide/1.concepts/3.rendering.md +++ b/docs/content/2.guide/1.concepts/3.rendering.md @@ -76,5 +76,3 @@ At the moment, every page (or **route**) of a Nuxt application must use the same Traditionally, server-side and universal rendering was only possible using Node.js. Nuxt 3 takes it to another level by directly rendering code in CDN edge workers, reducing latency and costs. Nitro is the new [server engine](/guide/concepts/server-engine) that powers Nuxt 3. It offers cross-platform support for Node.js, Deno, Workers, and more. Nitro's design is platform-agnostic and allows rendering a Nuxt application at the edge, closer to your users, allowing replication and further optimizations. - -[Deploy your Nuxt 3 application on serverless providers](/guide/deployment/presets) diff --git a/docs/content/2.guide/1.concepts/index.md b/docs/content/2.guide/1.concepts/index.md index c24a4a1fcd..1cef158d12 100644 --- a/docs/content/2.guide/1.concepts/index.md +++ b/docs/content/2.guide/1.concepts/index.md @@ -3,4 +3,5 @@ title: Concepts layout.aside: true layout.asideClass: '' navigation.redirect: /guide/concepts/introduction +# navigation.collapse: true --- diff --git a/docs/content/2.guide/3.directory-structure/2.output.md b/docs/content/2.guide/3.directory-structure/2.output.md index c044b064fe..ec59e4ae1d 100644 --- a/docs/content/2.guide/3.directory-structure/2.output.md +++ b/docs/content/2.guide/3.directory-structure/2.output.md @@ -12,4 +12,4 @@ Nuxt creates the `.output/` directory when building your application for product You should not touch any files inside since the whole directory will be re-created when running `nuxt build`. :: -Use this directory to deploy your Nuxt application to production. Learn more in our [deployment section](/guide/deployment). +Use this directory to deploy your Nuxt application to production. Learn more in our [deployment section](/guide/deploy). diff --git a/docs/content/2.guide/3.directory-structure/index.md b/docs/content/2.guide/3.directory-structure/index.md index c2d7daa964..86be19b429 100644 --- a/docs/content/2.guide/3.directory-structure/index.md +++ b/docs/content/2.guide/3.directory-structure/index.md @@ -3,4 +3,5 @@ title: 'Directory structure' layout.aside: true layout.asideClass: '' navigation.redirect: /guide/directory-structure/nuxt +navigation.collapse: true --- diff --git a/docs/content/2.guide/5.deploy/1.node-server.md b/docs/content/2.guide/5.deploy/1.node-server.md new file mode 100644 index 0000000000..7795e33276 --- /dev/null +++ b/docs/content/2.guide/5.deploy/1.node-server.md @@ -0,0 +1,54 @@ +# Node.js Server + +Discover the Node.js server preset with Nitro to deploy on any Node hosting. + +::list + +- **Default output format** if none is specified or auto-detected
+- Loads only the required chunks to render the request for optimal cold start timing
+- 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 +node .output/server/index.mjs +``` + +## Example + +```bash +$ node .output/server/index.mjs +Listening on http://localhost:3000 +``` + +## Configuring defaults at runtime + +This preset will respect the following runtime environment variables: + +- `NITRO_PORT` or `PORT` (defaults to `3000`) +- `NITRO_HOST` or `HOST` (defaults to `'localhost'`) +- `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. + +### Using PM2 + +To use `pm2`, use an `ecosystem.config.js`: + +```js [ecosystem.config.js] +module.exports = { + apps: [ + { + name: 'NuxtAppName', + exec_mode: 'cluster', + instances: 'max', + script: './.output/server/index.mjs' + } + ] +} +``` + +## Learn more + +:ReadMore{link="https://nitro.unjs.io/deploy/node.html" title="the Nitro documentation for node-server preset"} diff --git a/docs/content/2.guide/5.deploy/2.static-hosting.md b/docs/content/2.guide/5.deploy/2.static-hosting.md new file mode 100644 index 0000000000..9a2149f937 --- /dev/null +++ b/docs/content/2.guide/5.deploy/2.static-hosting.md @@ -0,0 +1,42 @@ +# Static Hosting + +::alert{type=warning icon=🚧} +This feature is still experimental and under development for Nuxt 3. +:: + +There are two ways to deploy a Nuxt application to any static hosting services: + +- Static site generation (SSG) prerenders every route of your application at build time. For every page, Nuxt uses a crawler to generate a corresponding HTML file. +- Using `ssr: false` to produce a pure client-side output. + +## Prerendering + +Use the [`nuxi generate` command](/api/commands/generate) to build your application. The HTML files will be generated in the `.output/public` directory. + +```bash +npx nuxi generate +``` + +## Client-side only rendering + +If you don't want to prerender your routes, another way of using static hosting is to set the `ssr` property to `false` in the `nuxt.config` file. The `nuxi build` command will then output an `index.html` entrypoint like a classic client-side Vue.js application. + +```ts [nuxt.config.ts|js] +defineNuxtConfig({ + ssr: false +}) +``` + +## Advanced + +You can manually specify routes that [Nitro](http://localhost:4000/guide/concepts/server-engine) will fetch and prerender during the build. + +```ts [nuxt.config.ts|js] +defineNuxtConfig({ + nitro: { + prerender: { + routes: ['/user/1', '/user/2'] + } + } +}) +``` diff --git a/docs/content/2.guide/5.deploy/3.presets.md b/docs/content/2.guide/5.deploy/3.presets.md new file mode 100644 index 0000000000..489d8f3b50 --- /dev/null +++ b/docs/content/2.guide/5.deploy/3.presets.md @@ -0,0 +1,37 @@ +# Deployment 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 use the [Nuxt config](/guide/directory-structure/nuxt.config) to explicitly set the preset to use: + +```js [nuxt.config.js|ts] +export default { + nitro: { + preset: 'node-server' + } +} +``` + +Or directly use the `NITRO_PRESET` environment variable when running `nuxt build`: + +```bash +NITRO_PRESET=node-server nuxt build +``` + +🔎 Check [the Nitro deployment](https://nitro.unjs.io/deploy/) for all possible deployment presets and providers. + +## Supported Hosting Providers + +Nuxt 3 can be deployed to several cloud providers with a minimal amount of configuration: + +- :IconCloud{class="h-5 w-4 inline mb-2"} [AWS](/guide/deploy/providers/aws) +- :LogoAzure{class="h-5 w-4 inline mb-2"} [Azure](/guide/deploy/providers/azure) +- :LogoCloudFlare{class="h-5 w-4 inline mb-2"} [CloudFlare](/guide/deploy/providers/cloudflare) +- :IconCloud{class="h-5 w-4 inline mb-2"} [Digital Ocean](/guide/deploy/providers/digitalocean) +- :LogoFirebase{class="h-5 w-4 inline mb-2"} [Firebase](/guide/deploy/providers/firebase) +- :IconCloud{class="h-5 w-4 inline mb-2"} [heroku](/guide/deploy/providers/heroku) +- :IconCloud{class="h-5 w-4 inline mb-2"} [layer0](/guide/deploy/providers/layer0) +- :LogoNetlify{class="h-5 w-4 inline mb-2"} [Netlify](/guide/deploy/providers/netlify) +- :IconCloud{class="h-5 w-4 inline mb-2"} [Render](/guide/deploy/providers/render) +- :IconCloud{class="h-5 w-4 inline mb-2"} [Stormkit](/guide/deploy/providers/stormkit) +- :LogoVercel{class="h-5 w-4 inline mb-2"} [Vercel](/guide/deploy/providers/vercel) diff --git a/docs/content/2.guide/5.deploy/index.md b/docs/content/2.guide/5.deploy/index.md new file mode 100644 index 0000000000..b5130f0ce8 --- /dev/null +++ b/docs/content/2.guide/5.deploy/index.md @@ -0,0 +1,7 @@ +--- +layout: + aside: true + asideClass: '' +navigation: + redirect: /guide/deploy/node-server +--- diff --git a/docs/content/2.guide/5.deploy/providers/aws.md b/docs/content/2.guide/5.deploy/providers/aws.md new file mode 100644 index 0000000000..747863fb41 --- /dev/null +++ b/docs/content/2.guide/5.deploy/providers/aws.md @@ -0,0 +1,11 @@ +--- +icon: IconCloud +--- + +# AWS + +How to deploy Nuxt to [AWS Lambda](https://aws.amazon.com/lambda/) + +## Learn more + +:ReadMore{link="https://nitro.unjs.io/deploy/providers/aws.html" title="the Nitro documentation for AWS deployment"} diff --git a/docs/content/2.guide/5.deploy/providers/azure.md b/docs/content/2.guide/5.deploy/providers/azure.md new file mode 100644 index 0000000000..1e8e04f228 --- /dev/null +++ b/docs/content/2.guide/5.deploy/providers/azure.md @@ -0,0 +1,18 @@ +--- +icon: LogoAzure +--- + +# Azure + +How to deploy to [Azure Static Web Apps](https://azure.microsoft.com/en-us/services/app-service/static/) or [Azure Functions](https://azure.microsoft.com/en-us/services/functions). + +::list + +- Support for serverless SSR build +- Auto-detected when deploying +- Minimal configuration required +:: + +## Learn more + +:ReadMore{link="https://nitro.unjs.io/deploy/providers/azure.html" title="the Nitro documentation for Azure deployment"} diff --git a/docs/content/2.guide/5.deploy/providers/cloudflare.md b/docs/content/2.guide/5.deploy/providers/cloudflare.md new file mode 100644 index 0000000000..16bf8c37b7 --- /dev/null +++ b/docs/content/2.guide/5.deploy/providers/cloudflare.md @@ -0,0 +1,18 @@ +--- +icon: LogoCloudFlare +--- + +# Cloudflare Workers + +How to deploy Nuxt to [Cloudflare Workers](https://workers.cloudflare.com/). + +::list + +- Support for Workers build output +- Zero-millisecond cold start with edge-side rendering +- Minimal configuration required +:: + +## Learn more + +:ReadMore{link="https://nitro.unjs.io/deploy/providers/cloudflare.html" title="the Nitro documentation for Cloudflare deployment"} diff --git a/docs/content/2.guide/5.deploy/providers/digitalocean.md b/docs/content/2.guide/5.deploy/providers/digitalocean.md new file mode 100644 index 0000000000..d8e658c89a --- /dev/null +++ b/docs/content/2.guide/5.deploy/providers/digitalocean.md @@ -0,0 +1,11 @@ +--- +icon: IconCloud +--- + +# DigitalOcean + +Nitro supports deploying on the [Digital Ocean App Platform](https://docs.digitalocean.com/products/app-platform/) with minimal configuration. + +## Learn more + +:ReadMore{link="https://nitro.unjs.io/deploy/providers/digitalocean.html" title="the Nitro documentation for DigitalOcean deployment"} diff --git a/docs/content/2.guide/5.deploy/providers/firebase.md b/docs/content/2.guide/5.deploy/providers/firebase.md new file mode 100644 index 0000000000..cb89045c86 --- /dev/null +++ b/docs/content/2.guide/5.deploy/providers/firebase.md @@ -0,0 +1,15 @@ +--- +icon: LogoFirebase +--- + +# Firebase Hosting + +How to deploy Nuxt to [Firebase Hosting](https://firebase.google.com/docs/hosting). + +Nitro supports [Firebase Hosting](https://firebase.google.com/docs/hosting) with Cloud Functions out of the box. + +**Note**: You need to be on the **Blaze plan** to use Nitro with Cloud Functions. + +## Learn more + +:ReadMore{link="https://nitro.unjs.io/deploy/providers/firebase.html" title="the Nitro documentation for Firebase deployment"} diff --git a/docs/content/2.guide/5.deploy/providers/heroku.md b/docs/content/2.guide/5.deploy/providers/heroku.md new file mode 100644 index 0000000000..f422bde490 --- /dev/null +++ b/docs/content/2.guide/5.deploy/providers/heroku.md @@ -0,0 +1,11 @@ +--- +icon: IconCloud +--- + +# Heroku + +How to deploy Nuxt to [Heroku](https://www.heroku.com/). + +## Learn more + +:ReadMore{link="https://nitro.unjs.io/deploy/providers/heroku.html" title="the Nitro documentation for Heroku deployment"} diff --git a/docs/content/2.guide/5.deploy/providers/index.md b/docs/content/2.guide/5.deploy/providers/index.md new file mode 100644 index 0000000000..dc762ec9a6 --- /dev/null +++ b/docs/content/2.guide/5.deploy/providers/index.md @@ -0,0 +1,3 @@ +--- +navigation: false +--- diff --git a/docs/content/2.guide/5.deploy/providers/layer0.md b/docs/content/2.guide/5.deploy/providers/layer0.md new file mode 100644 index 0000000000..b8f0fd6e58 --- /dev/null +++ b/docs/content/2.guide/5.deploy/providers/layer0.md @@ -0,0 +1,13 @@ +--- +icon: IconCloud +--- + +# Layer0 + +Nitro provides a built-in preset to generate output format compatible with [Layer0](https://www.layer0.co/). + +Layer0 extends the capabilities of a traditional CDN by not only hosting your static content, but also providing server-side rendering for progressive web applications as well as caching both your APIs and HTML at the network edge to provide your users with the fastest browsing experience. + +## Learn more + +:ReadMore{link="https://nitro.unjs.io/deploy/providers/layer0.html" title="the Nitro documentation for Layer0 deployment"} diff --git a/docs/content/2.guide/5.deployment/4.netlify.md b/docs/content/2.guide/5.deploy/providers/netlify.md similarity index 69% rename from docs/content/2.guide/5.deployment/4.netlify.md rename to docs/content/2.guide/5.deploy/providers/netlify.md index 64ce5cebf7..57fe9a80d1 100644 --- a/docs/content/2.guide/5.deployment/4.netlify.md +++ b/docs/content/2.guide/5.deploy/providers/netlify.md @@ -4,7 +4,7 @@ icon: LogoNetlify # Netlify -How to deploy Nuxt to Netlify. +How to deploy Nuxt to [Netlify](https://www.netlify.com/). ::list @@ -24,10 +24,10 @@ However, if you want to add custom redirects, you can do so by adding a [`_redir Just push to your git repository [as you would normally do for Netlify](https://docs.netlify.com/configure-builds/get-started/). -## More information +## Deploy to Netlify Edge -See [more information on the Lambda preset](/guide/deployment/presets/lambda) for full details. +By setting `NITRO_PRESET` environement variable to `netlify_edge` you can use [Netlify Edge Functions](https://docs.netlify.com/netlify-labs/experimental-features/edge-functions/) to render Nuxt app! -## Demo +## Learn more -A live demo is available on . +:ReadMore{link="https://nitro.unjs.io/deploy/providers/netlify.html" title="the Nitro documentation for Netlify deployment"} diff --git a/docs/content/2.guide/5.deploy/providers/render.md b/docs/content/2.guide/5.deploy/providers/render.md new file mode 100644 index 0000000000..4da7a28c80 --- /dev/null +++ b/docs/content/2.guide/5.deploy/providers/render.md @@ -0,0 +1,11 @@ +--- +icon: IconCloud +--- + +# Render + +How to deploy Nuxt to [Render](https://render.com/) + +## Learn more + +:ReadMore{link="https://nitro.unjs.io/deploy/providers/render.html" title="the Nitro documentation for Render deployment"} diff --git a/docs/content/2.guide/5.deploy/providers/stormkit.md b/docs/content/2.guide/5.deploy/providers/stormkit.md new file mode 100644 index 0000000000..942f91757c --- /dev/null +++ b/docs/content/2.guide/5.deploy/providers/stormkit.md @@ -0,0 +1,11 @@ +--- +icon: IconCloud +--- + +# StormKit + +How to deploy Nuxt to [StormKit](https://www.stormkit.io/). + +## Learn more + +:ReadMore{link="https://nitro.unjs.io/deploy/providers/stormkit.html" title="the Nitro documentation for StormKit deployment"} diff --git a/docs/content/2.guide/5.deployment/6.vercel.md b/docs/content/2.guide/5.deploy/providers/vercel.md similarity index 88% rename from docs/content/2.guide/5.deployment/6.vercel.md rename to docs/content/2.guide/5.deploy/providers/vercel.md index 7372052b77..b3f21e2793 100644 --- a/docs/content/2.guide/5.deployment/6.vercel.md +++ b/docs/content/2.guide/5.deploy/providers/vercel.md @@ -13,6 +13,17 @@ Nuxt on Vercel supports server-rendered pages and API routes. - No configuration required :: +## Git + +1. Push your code to your git repository (GitHub, GitLab, Bitbucket). +2. [Import your project](https://vercel.com/new) into Vercel. +3. Vercel will detect that you are using Nuxt and will enable the correct settings for your deployment. +4. Your application is deployed! (e.g. [nuxt.vercel.app](https://nuxt.vercel.app/)) + +After your project has been imported and deployed, all subsequent pushes to branches will generate [Preview Deployments](https://vercel.com/docs/concepts/deployments/environments#preview), and all changes made to the Production Branch (commonly “main”) will result in a [Production Deployment](https://vercel.com/docs/concepts/deployments/environments#production). + +Learn more about Vercel’s [Git Integration](https://vercel.com/docs/concepts/git). + ## CLI 1. Install the [Vercel CLI](https://vercel.com/cli). @@ -25,21 +36,6 @@ npx nuxi init -t v3-vercel vercel ``` -## Git +## Learn more -1. Push your code to your git repository (GitHub, GitLab, Bitbucket). -2. [Import your project](https://vercel.com/new) into Vercel. -3. Vercel will detect that you are using Nuxt and will enable the correct settings for your deployment. -4. Your application is deployed! (e.g. [nuxt.vercel.app](https://nuxt.vercel.app/)) - -After your project has been imported and deployed, all subsequent pushes to branches will generate [Preview Deployments](https://vercel.com/docs/concepts/deployments/environments#preview), and all changes made to the Production Branch (commonly “main”) will result in a [Production Deployment](https://vercel.com/docs/concepts/deployments/environments#production). - -Learn more about Vercel’s [Git Integration](https://vercel.com/docs/concepts/git). - -## More information - -See [more information on the node preset](/guide/deployment/presets/node) for full details. - -## Demo - -A live demo is available at . +:ReadMore{link="https://nitro.unjs.io/deploy/providers/vercel.html" title="the Nitro documentation for Vercel deployment"} diff --git a/docs/content/2.guide/5.deployment/1.azure.md b/docs/content/2.guide/5.deployment/1.azure.md deleted file mode 100644 index 8c2053cd81..0000000000 --- a/docs/content/2.guide/5.deployment/1.azure.md +++ /dev/null @@ -1,184 +0,0 @@ ---- -icon: LogoAzure ---- - -# Azure - -How to deploy to Azure Static Web Apps or Azure Functions with Nitro. - -## Azure Static Web Apps - -How to deploy to Azure Static Web Apps with Nitro. - -::list - -- Support for serverless SSR build -- Auto-detected when deploying -- Minimal configuration required -:: - -### Setup - -Azure Static Web Apps are designed to be deployed continuously in a [GitHub Actions workflow](https://docs.microsoft.com/en-us/azure/static-web-apps/github-actions-workflow). By default, Nitro will detect this deployment environment and enable the `azure` preset. - -### Local preview - -You can invoke a development environment to preview before deploying. - -```bash -NITRO_PRESET=azure yarn build -npx @azure/static-web-apps-cli start .output/public --api-location .output/server -``` - -### Deploy from CI/CD via GitHub Actions - -When you link your GitHub repository to Azure Static Web Apps, a workflow file is added to the repository. - -When you are asked to select your framework, select custom and provide the following information: - -| Input | Value | -| --- | --- | -| **app_location** | '/' | -| **api_location** | '.output/server' | -| **output_location** | '.output/public' | - -If you miss this step, you can always find the build configuration section in your workflow and update the build configuration: - -```yml{}[.github/workflows/azure-static-web-apps-.yml] -###### Repository/Build Configurations ###### -app_location: '/' -api_location: '.output/server' -output_location: '.output/public' -###### End of Repository/Build Configurations ###### -``` - -#### Note - -Pending an update in the [Azure Static Web Apps workflow](https://github.com/Azure/static-web-apps-deploy), you will also need to run the following in your root directory: - -```bash -mkdir -p .output/server -touch .output/server/.gitkeep -git add -f .output/server/.gitkeep -``` - -That's it! Now Azure Static Web Apps will automatically deploy your Nitro-powered Nuxt application on push. - -### Demo - -A live demo is available on . - -## Azure Functions - -::list - -- Support for serverless SSR build -- No configuration required -- Static assets served from Azure Function -:: - -### Setup - -```ts [nuxt.config.js|ts] -export default { - nitro: { - preset: 'azure-functions' - } -} -``` - -::alert -If you encounter any issues, please ensure you're using a Node.js 14+ runtime. You can find more information about [how to set the Node version in the Azure docs](https://docs.microsoft.com/en-us/azure/azure-functions/functions-reference-node?tabs=v2#setting-the-node-version). -:: - -### Local preview - -Install [Azure Functions Core Tools](https://docs.microsoft.com/en-us/azure/azure-functions/functions-run-local) if you want to test locally. - -You can invoke a development environment from the serverless directory. - -```bash -NITRO_PRESET=azure-functions yarn build -cd .output -func start -``` - -You can now visit in your browser and browse your site running locally on Azure Functions. - -### Deploy from your local machine - -To deploy, just run the following command: - -```bash -# To publish the bundled zip file -az functionapp deployment source config-zip -g -n --src dist/deploy.zip -# Alternatively you can publish from source -cd dist && func azure functionapp publish --javascript -``` - -### Deploy from CI/CD via GitHub Actions - -First, obtain your Azure Functions Publish Profile and add it as a secret to your GitHub repository settings following [these instructions](https://github.com/Azure/functions-action#using-publish-profile-as-deployment-credential-recommended). - -Then create the following file as a workflow: - -```yml{}[.github/workflows/azure.yml] -name: azure -on: - push: - branches: - - main - pull_request: - branches: - - main -jobs: - deploy: - runs-on: ${{ matrix.os }} - strategy: - matrix: - os: [ ubuntu-latest ] - node: [ 14 ] - steps: - - uses: actions/setup-node@v2 - with: - node-version: ${{ matrix.node }} - - - name: Checkout - uses: actions/checkout@master - - - name: Get yarn cache directory path - id: yarn-cache-dir-path - run: echo "::set-output name=dir::$(yarn cache dir)" - - - uses: actions/cache@v2 - id: yarn-cache - with: - path: ${{ steps.yarn-cache-dir-path.outputs.dir }} - key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }} - restore-keys: | - ${{ runner.os }}-yarn-azure - - - name: Install Dependencies - if: steps.cache.outputs.cache-hit != 'true' - run: yarn - - - name: Build - run: npm run build - env: - NITRO_PRESET: azure-functions - - - name: 'Deploy to Azure Functions' - uses: Azure/functions-action@v1 - with: - app-name: - package: .output/deploy.zip - publish-profile: ${{ secrets.AZURE_FUNCTIONAPP_PUBLISH_PROFILE }} -``` - -### Optimizing Azure Functions - -Consider [turning on immutable packages](https://docs.microsoft.com/en-us/azure/app-service/deploy-run-package) to support running your app from the zip file. This can speed up cold starts. - -### Demo - -A live demo is available on . diff --git a/docs/content/2.guide/5.deployment/2.cloudflare.md b/docs/content/2.guide/5.deployment/2.cloudflare.md deleted file mode 100644 index faedab836d..0000000000 --- a/docs/content/2.guide/5.deployment/2.cloudflare.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -icon: LogoCloudFlare ---- - -# Cloudflare Workers - -How to deploy Nuxt to Cloudflare Workers. - -::list - -- Support for Workers build output -- Zero-millisecond cold start with edge-side rendering -- Minimal configuration required -:: - -## Setup - -Login to your [Cloudflare Workers](https://workers.cloudflare.com) account and obtain your `account_id` from the sidebar. - -Create a `wrangler.toml` in your root directory: - -```ini{}[wrangler.toml] -name = "playground" -type = "javascript" -account_id = "" -workers_dev = true -route = "" -zone_id = "" - -[site] -bucket = ".output/public" -entry-point = ".output" - -[build] -command = "true" -upload.format = "service-worker" -``` - -## Testing locally - -You can use [miniflare](https://miniflare.dev/), a local Cloudflare Workers development server, to test your app locally: - -```bash -NITRO_PRESET=cloudflare yarn build -npx miniflare .output/server/index.mjs --site .output/public -``` - -## Deploy from your local machine using wrangler - -Install [wrangler](https://github.com/cloudflare/wrangler) and login to your Cloudflare account: - -```bash -npm i @cloudflare/wrangler -g -wrangler login -``` - -Generate website with `cloudflare` preset: - -```bash -NITRO_PRESET=cloudflare yarn build -``` - -You can preview locally: - -```bash -wrangler dev -``` - -Publish: - -```bash -wrangler publish -``` - -## Deploy within CI/CD using GitHub Actions - -Create a token according to [the wrangler action docs](https://github.com/marketplace/actions/deploy-to-cloudflare-workers-with-wrangler#authentication) and set `CF_API_TOKEN` in your repository config on GitHub. - -Create `.github/workflows/cloudflare.yml`: - -```yml{}[.github/workflows/cloudflare.yml] -name: cloudflare - -on: - push: - branches: - - main - pull_request: - branches: - - main - -jobs: - ci: - runs-on: ${{ matrix.os }} - - strategy: - matrix: - os: [ ubuntu-latest ] - node: [ 14 ] - - steps: - - uses: actions/setup-node@v1 - with: - node-version: ${{ matrix.node }} - - - name: Checkout - uses: actions/checkout@master - - - name: Cache node_modules - uses: actions/cache@v2 - with: - path: node_modules - key: ${{ matrix.os }}-node-v${{ matrix.node }}-deps-${{ hashFiles(format('{0}{1}', github.workspace, '/yarn.lock')) }} - - - name: Install Dependencies - if: steps.cache.outputs.cache-hit != 'true' - run: yarn - - - name: Build - run: yarn build - env: - NITRO_PRESET: cloudflare - - - name: Publish to Cloudflare - uses: cloudflare/wrangler-action@1.3.0 - with: - apiToken: ${{ secrets.CF_API_TOKEN }} -``` - -## More information - -See [more information on the service worker preset](/guide/deployment/presets/service-worker) for full details. - -## Demo - -A live demo is available on . diff --git a/docs/content/2.guide/5.deployment/3.firebase.md b/docs/content/2.guide/5.deployment/3.firebase.md deleted file mode 100644 index 6dc41eafb6..0000000000 --- a/docs/content/2.guide/5.deployment/3.firebase.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -icon: LogoFirebase ---- - -# Firebase Hosting - -How to deploy Nuxt to Firebase Hosting. - -::list - -- Support for serverless build -- Minimal configuration required -:: - -## Setup - -Nitro supports [Firebase Hosting](https://firebase.google.com/docs/hosting) with Cloud Functions out of the box. - -**Note**: You need to be on the **Blaze plan** to use Nitro with Cloud Functions. - -### Using Nitro - -If you don't already have a `firebase.json` in your root directory, Nitro will create one the first time you run it. In this file, you will need to replace `` with the ID of your Firebase project. - -This file should then be committed to version control. You can also create a `.firebaserc` file if you don't want to manually pass your project ID to your `firebase` commands (with `--project `): - -```json [.firebaserc] -{ - "projects": { - "default": "" - } -} -``` - -Then, just add Firebase dependencies to your project: - -::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. - -#### Install Firebase CLI globally - -::code-group - -```bash [Yarn] -yarn global add firebase-tools -``` - -```bash [NPM] -npm install -g firebase-tools -``` - -:: - -#### Initialize your Firebase project - -```bash -firebase login -firebase init hosting -``` - -When prompted, you can enter `.output/public` as the public directory. In the next step, **do not** configure your project as a single-page app. - -Once complete, add the following to your `firebase.json` to enable server rendering in Cloud Functions: - -```json [firebase.json] -{ - "functions": { "source": ".output/server" }, - "hosting": [ - { - "site": "", - "public": ".output/public", - "cleanUrls": true, - "rewrites": [{ "source": "**", "function": "server" }] - } - ] -} -``` - -You can find more details in the [Firebase documentation](https://firebase.google.com/docs/hosting/quickstart). - -## Local preview - -You can preview a local version of your site if you need to test things out without deploying. - -```bash -NITRO_PRESET=firebase yarn build -firebase emulators:start -``` - -## Deploy to Firebase Hosting via CLI - -Deploying to Firebase Hosting is a simple matter of just running the `firebase deploy` command. - -```bash -NITRO_PRESET=firebase yarn build -firebase deploy -``` - -## Demo site - -A live demo is available on . diff --git a/docs/content/2.guide/5.deployment/5.pm2.md b/docs/content/2.guide/5.deployment/5.pm2.md deleted file mode 100644 index 5232f90504..0000000000 --- a/docs/content/2.guide/5.deployment/5.pm2.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -icon: LogoPM2 ---- - -# PM2 - -How to deploy Nuxt to a Node.js hosting using PM2. - -::list - -- Support for ultra-minimal SSR build -- Zero-millisecond cold start -- More configuration required -:: - -## Setup - -Make sure another preset isn't set in `nuxt.config`. - -```js [nuxt.config.js|ts] -export default { - nitro: { - // this is the default preset so you can also just omit it entirely - // preset: 'node-server' - } -} -``` - -## Deployment - -After running `yarn build`, all the required files are located in the `.output` folder. Static assets are in the `public` subdirectory and the server with its dependencies is within the `server` subdirectory. - -This `.output` folder can be deployed to your Node.js host and the server can be run using [`pm2`](https://pm2.keymetrics.io/docs/usage/quick-start/). - -To start the server in production mode, run: - -```bash -node .output/server/index.mjs -``` - -For example, using `pm2`: - -```js [ecosystem.config.js] -module.exports = { - apps: [ - { - name: 'NuxtAppName', - exec_mode: 'cluster', - instances: 'max', - script: './.output/server/index.mjs' - } - ] -} -``` - -## More information - -See more information on the [server preset](/guide/deployment/presets/server). diff --git a/docs/content/2.guide/5.deployment/99.presets.md b/docs/content/2.guide/5.deployment/99.presets.md deleted file mode 100644 index 27eb5a7574..0000000000 --- a/docs/content/2.guide/5.deployment/99.presets.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -icon: IconPresets ---- - -# Presets - -Nuxt provides four generic presets that you can use out-of-the-box. - -::list{type=success} - -- [Node.js server *(default)*](/guide/deployment/presets/server) -- [Node.js function](/guide/deployment/presets/node) -- [Lambda function](/guide/deployment/presets/lambda) -- [Service worker](/guide/deployment/presets/service-worker) -:: - -If you need to [create a custom preset](/guide/deployment/presets/custom), that's possible too. 🚀 diff --git a/docs/content/2.guide/5.deployment/99.presets/custom.md b/docs/content/2.guide/5.deployment/99.presets/custom.md deleted file mode 100644 index cbf95c00b6..0000000000 --- a/docs/content/2.guide/5.deployment/99.presets/custom.md +++ /dev/null @@ -1,55 +0,0 @@ -# Custom build preset (advanced) - -Get full control of Nuxt Nitro output to deploy on any kind of hosting platform. - -::list{type=info} - -- Allows full customization -- This is an advanced usage pattern -:: - -::alert{icon=IconPresets} -Back to [presets list](/guide/deployment/presets). -:: - -## Setup - -You can create your own custom-built preset. See [the provided presets](https://github.com/unjs/nitro/tree/main/src/presets) for examples. - -### Inline preset definition - -You can define everything that a custom preset would configure directly in the Nitro options: - -```ts [nuxt.config.js|ts] -export default { - nitro: { - // preset options - } -} -``` - -### Reusable preset - -You can also define a preset in a separate file (or publish it as a separate npm package). - -```ts [my-preset/index.ts] -import type { NitroPreset } from 'nitropack' - -const myPreset: NitroPreset = { - // Your custom configuration -} - -export default myPreset -``` - -Then in your `nuxt.config` you can specify that Nitro should use your custom preset: - -```ts [nuxt.config.js|ts] -import { fileURLToPath } from 'node:url' - -export default { - nitro: { - preset: fileURLToPath(new URL('./my-preset', import.meta.url)) - } -} -``` diff --git a/docs/content/2.guide/5.deployment/99.presets/lambda.md b/docs/content/2.guide/5.deployment/99.presets/lambda.md deleted file mode 100644 index 47c1fd7614..0000000000 --- a/docs/content/2.guide/5.deployment/99.presets/lambda.md +++ /dev/null @@ -1,44 +0,0 @@ -# Lambda function - -Discover the Lambda function preset with Nitro to deploy Nuxt to any lambda-compatible serverless platform. - -::alert{icon=IconPresets} -Back to [presets list](/guide/deployment/presets). -:: - -## Usage - -You can use the [Nuxt config](/guide/directory-structure/nuxt.config) to explicitly set the preset to use: - -```ts [nuxt.config.js|ts] -export default { - nitro: { - preset: 'aws-lambda' - } -} -``` - -Or directly use the `NITRO_PRESET` environment variable when running `nuxt build`: - -```bash -NITRO_PRESET=aws-lambda npx nuxt build -``` - -::alert -AWS Lambda [defaults to payload version v2](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html). This Nitro preset supports both v1 and v2 payloads. -:: - -### Entry point - -When running `nuxt build` with the Lambda preset, the result will be an entry point that exports a handler function that responds to an event and returns a response. - -This entry point 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 deployment. - -```ts -import { handler } from './.output/server' - -// Use programmatically -const { statusCode, headers, body } = handler({ rawPath: '/' }) -``` diff --git a/docs/content/2.guide/5.deployment/99.presets/node.md b/docs/content/2.guide/5.deployment/99.presets/node.md deleted file mode 100644 index a072231d44..0000000000 --- a/docs/content/2.guide/5.deployment/99.presets/node.md +++ /dev/null @@ -1,64 +0,0 @@ -# Node.js function - -Discover the Node.js function preset with Nitro to attach Nuxt as a middleware to any Node.js server. - -::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 -:: - -::alert{icon=IconPresets} -Back to [presets list](/guide/deployment/presets). -:: - -## Usage - -You can use the [Nuxt config](/guide/directory-structure/nuxt.config) to explicitly set the preset to use: - -```js [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 -``` - -## Entry point - -When running `nuxt build` with the Node preset, the result will be an entry point 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 - -### Express middleware - -```js -import express from 'express' -import handler from './.output/server' - -const app = express() - -app.use(handler) -app.listen(3000) -``` - -### Node server - -```js -import { createServer } from 'node:http' -import handler from './.output/server' - -const server = createServer(handler) -server.listen(8080) -``` diff --git a/docs/content/2.guide/5.deployment/99.presets/server.md b/docs/content/2.guide/5.deployment/99.presets/server.md deleted file mode 100644 index aa17052cfb..0000000000 --- a/docs/content/2.guide/5.deployment/99.presets/server.md +++ /dev/null @@ -1,80 +0,0 @@ -# Node.js server - -Discover the Node.js server preset with Nitro to deploy on any Node hosting. - -::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 -:: - -::alert{icon=IconPresets} -Back to [presets list](/guide/deployment/presets). -:: - -## Usage - -You can use the [Nuxt config](/guide/directory-structure/nuxt.config) to explicitly set the preset to use: - -```js [nuxt.config.js|ts] -export default { - nitro: { - preset: 'node-server' - } -} -``` - -Or directly use the `NITRO_PRESET` environment variable when running `nuxt build`: - -```bash -NITRO_PRESET=node-server npx nuxt build -``` - -## 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 -node .output/server/index.mjs -``` - -## Example - -```bash -$ node .output/server/index.mjs -Listening on http://localhost:3000 -``` - -## Configuring defaults at runtime - -This preset will respect the following runtime environment variables: - -- `NUXT_PORT` or `PORT` (defaults to `3000`) -- `NUXT_HOST` or `HOST` (defaults to `'localhost'`) -- `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. - -## Server timings - -You can enable the `nitro.timing` option to have the logs about the chunk loading and cold start performance. - -```js [nuxt.config.js|ts] -export default { - nitro: { - preset: 'node-server', - timing: true - } -} -``` - -```bash -$ node .output/server/index.mjs -> Nitro Start (3ms) -Listening on http://localhost:3000 -> Load chunks/nitro/static (0ms) -> Load chunks/app/render (1ms) -> Load chunks/app/client.manifest (0ms) -> Load chunks/index (3ms) -> Load chunks/app/server (2ms) -> Load chunks/app/vue3 (0ms) -``` diff --git a/docs/content/2.guide/5.deployment/99.presets/service-worker.md b/docs/content/2.guide/5.deployment/99.presets/service-worker.md deleted file mode 100644 index be499da71f..0000000000 --- a/docs/content/2.guide/5.deployment/99.presets/service-worker.md +++ /dev/null @@ -1,42 +0,0 @@ -# Service worker - -Explore the Service worker preset with Nitro to push the boundaries of Nuxt rendering to the edge. - -::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](/guide/deployment/presets). -:: - -::alert{type=warning} -Deployment as a service worker has some limitations since SSR code is not running in Node.js environment but pure JavaScript. -:: - -## Usage - -You can use the [Nuxt config](/guide/directory-structure/nuxt.config) to explicitly set the preset to use: - -```js [nuxt.config.js|ts] -export default { - nitro: { - 'service-worker' - } -} -``` - -Or directly use the `NITRO_PRESET` environment variable when running `nuxt build`: - -```bash -NITRO_PRESET=service-worker npx nuxt build -``` - -## Entry point - -The worker preset produces a service worker that can provide full HTML rendering within a worker context (for example [Cloudflare Workers](/guide/deployment/cloudflare)). It registers appropriate handlers for `fetch`, `install` and `activate`. - -For more information, you can check out the [source code](https://github.com/unjs/nitro/blob/main/src/presets/service-worker.ts). diff --git a/docs/content/2.guide/5.deployment/index.md b/docs/content/2.guide/5.deployment/index.md deleted file mode 100644 index 8caec21140..0000000000 --- a/docs/content/2.guide/5.deployment/index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: - aside: true - asideClass: '' -navigation: - collapse: true - exclusive: false - redirect: /guide/deployment/presets ---- diff --git a/docs/content/2.guide/6.going-further/index.md b/docs/content/2.guide/6.going-further/index.md index 99696475b2..9a6c2b245d 100644 --- a/docs/content/2.guide/6.going-further/index.md +++ b/docs/content/2.guide/6.going-further/index.md @@ -3,4 +3,5 @@ title: Going further layout.aside: true layout.asideClass: '' navigation.redirect: /guide/going-further/tooling +# navigation.collapse: true --- diff --git a/docs/content/3.api/5.commands/generate.md b/docs/content/3.api/5.commands/generate.md new file mode 100644 index 0000000000..c81d9e05d2 --- /dev/null +++ b/docs/content/3.api/5.commands/generate.md @@ -0,0 +1,11 @@ +# `nuxi generate` + +```{bash} +npx nuxi generate [rootDir] +``` + +The `generate` command pre-renders every route of your application and stores the result in plain HTML files that you can deploy on any static hosting services. The command triggers the `nuxi build` command with the `prerender` argument set to `true` + +Option | Default | Description +-------------------------|-----------------|------------------ +`rootDir` | `.` | The root directory of the application to generate