docs: add deployment (#211)

Co-authored-by: Alexander Lichter <manniL@gmx.net>
Co-authored-by: Pooya Parsa <pyapar@gmail.com>

docs/content/1.get-started/1.installation.md

@@ -13,7 +13,7 @@ Recommended setup is:
 * **Vetur extension** [[Download](https://marketplace.visualstudio.com/items?itemName=octref.vetur)]
 * **Yarn package manager** [[Download](https://classic.yarnpkg.com/en/docs/install#windows-stable)]
 
-<sup>*</sup> If you already have NodeJS installed, check with `node --version` to ensure using `v14` or `v16`.
+<sup>*</sup> If you already have Node.js installed, check with `node --version` to ensure using `v14` or `v16`.
 
 
 ## Create project

docs/content/3.server/1.api.md

@@ -26,7 +26,7 @@ export default async (req, res) => {
 }
 ```
 
-**Example:** Using NodeJS style
+**Example:** Using Node.js style
 
 ```js [server/api/node.ts]
 export default async (req, res) => {

docs/content/6.deployment/1.platforms.md

@@ -0,0 +1,13 @@
+# Platforms
+
+Nuxt Nitro comes with support out-of-the-box for a number of platforms.
+
+1. [Azure Functions](/deployment/platforms/azure-functions)
+1. [Azure Static Web Apps](/deployment/platforms/azure)
+1. [Cloudflare](/deployment/platforms/cloudflare)
+1. [Firebase](/deployment/platforms/firebase)
+1. [Netlify](/deployment/platforms/netlify)
+1. [PM2](/deployment/platforms/pm2)
+1. [Vercel](/deployment/platforms/vercel)
+
+We'd welcome pull requests adding support for more, or you can release [a custom preset](/deployment/presets/custom) as a separate package.

docs/content/6.deployment/2.presets.md

@@ -0,0 +1,12 @@
+# Presets (advanced)
+
+There are four provided generic presets for Nuxt Nitro that you can use out-of-the-box:
+
+1. [Node.js server](/deployment/presets/server)
+2. [Node.js function](/deployment/presets/node)
+3. [Lambda function](/deployment/presets/lambda)
+4. [Service worker](/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).

docs/content/6.deployment/platforms/azure-functions.md

@@ -0,0 +1,112 @@
+# Azure Functions
+
+> How to deploy Nuxt to Azure Functions with Nuxt Nitro.
+
+ - Support for serverless SSR build
+ - No configuration required
+ - Static assets served from Azure Function
+
+## Setup
+
+```js [nuxt.config.js]
+export default {
+  nitro: {
+    preset: 'azure_functions'
+  }
+}
+```
+
+## 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 http://localhost:7071/ 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 <resource-group> -n <app-name> --src dist/deploy.zip
+# Alternatively you can publish from source
+cd dist && func azure functionapp publish --javascript <app-name>
+```
+
+## 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: [ 12 ]
+
+    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
+
+      - name: 'Deploy to Azure Functions'
+        uses: Azure/functions-action@v1
+        with:
+          app-name: <your-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 zipfile. This can speed up cold starts.
+
+## Demo
+
+A live demo is available on https://nuxt-nitro.azurewebsites.net/

docs/content/6.deployment/platforms/azure.md

@@ -0,0 +1,36 @@
+# Azure Static Web Apps
+
+> How to deploy Nuxt to Azure Static Web Apps with Nuxt Nitro.
+
+ - 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.
+
+## 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.
+
+Find the build configuration section in this workflow and update the build configuration:
+
+```yml{}[.github/workflows/azure-static-web-apps-<RANDOM_NAME>.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.

docs/content/6.deployment/platforms/cloudflare.md

@@ -0,0 +1,116 @@
+# Cloudflare Workers
+
+> How to deploy Nuxt to Cloudflare Workers with Nuxt Nitro.
+
+ - Support for serverless SSR build
+ - Zero millisecond cold start with edge 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 = "<the account_id you obtained>"
+workers_dev = true
+route = ""
+zone_id = ""
+
+[site]
+bucket = ".output/public"
+entry-point = ".output"
+```
+
+## 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](/presets/worker) for full details.
+
+## Demo
+
+A live demo is available on https://nitro-demo.nuxt.workers.dev/

docs/content/6.deployment/platforms/firebase.md

@@ -0,0 +1,84 @@
+# Firebase Hosting
+
+> How to deploy Nuxt to Firebase Hosting with Nuxt Nitro
+
+ - Support for serverless SSR build
+ - Minimal configuration required
+
+## Setup
+
+Nitro supports Firebase 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.
+
+### 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. All you will need to do is edit this to replace `<your_project_id>` with the project ID that you have chosen on Firebase.
+
+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 <your_project_id>):
+```json [.firebaserc]
+{
+  "projects": {
+    "default": "<your_project_id>"
+  }
+}
+```
+
+Then, just add Firebase dependencies to your project:
+
+```bash
+yarn add --dev 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
+yarn global install firebase-tools
+# Initialize your firebase project
+firebase login
+firebase init hosting
+```
+
+When prompted, you can enter `.output/public` as the public directory. **Don't** select that this will be 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": "<your_project_id>",
+      "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 https://nitro-demo-dfabe.web.app

docs/content/6.deployment/platforms/netlify.md

@@ -0,0 +1,23 @@
+# Netlify
+
+> How to deploy Nuxt to Netlify with Nuxt Nitro
+
+ - Support for serverless SSR build
+ - Auto-detected when deploying
+ - No configuration required
+
+## 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).
+
+## Deployment
+
+Just push to your git repository [as you would normally for Netlify](https://docs.netlify.com/configure-builds/get-started/).
+
+## More information
+
+See [more information on the lambda preset](/presets/lambda) for full details.
+
+## Demo
+
+A live demo is available on https://nuxt-nitro.netlify.app/

docs/content/6.deployment/platforms/pm2.md

@@ -0,0 +1,51 @@
+# PM2
+
+> How to deploy Nuxt to a Node.js host with Nuxt Nitro
+
+ - Support for ultra-minimal SSR build
+ - Zero millisecond cold start
+ - More configuration required
+
+## Setup
+
+Make sure another preset isn't set in `nuxt.config`.
+
+```ts [nuxt.config.js]
+export default {
+  nitro: {
+    // this is the default preset so you can also just omit it entirely
+    // preset: 'server'
+  }
+}
+```
+
+## Deployment
+
+After running `yarn build`, all you need is in the `.output` folder. Static assets are in the `public` subdirectory and the server and its dependencies are 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/).
+
+To start the server in production mode, run:
+
+```bash
+node .output/server
+```
+
+For example, using `pm2`:
+
+```js [ecosystem.config.js]
+module.exports = {
+  apps: [
+    {
+      name: 'NuxtAppName',
+      exec_mode: 'cluster',
+      instances: 'max',
+      script: './.output/server/index.js'
+    }
+  ]
+}
+```
+
+## More information
+
+See [more information on the server preset](/presets/server).

docs/content/6.deployment/platforms/vercel.md

@@ -0,0 +1,23 @@
+# Vercel
+
+> How to deploy Nuxt to Vercel with Nuxt Nitro
+
+ - Support for serverless SSR build
+ - Auto-detected when deploying
+ - No configuration required
+
+## Setup
+
+By default, Vercel will run your `build` script in the `package.json` and automatically detect the built entrypoint within `.vercel_build_output/`.
+
+## Deployment
+
+Just push to your git repository [as you would normally for Vercel](https://vercel.com/docs/git).
+
+## More information
+
+See [more information on the node preset](/presets/node) for full details.
+
+## Demo
+
+A live demo is available at https://nitro-demo.vercel.app/

docs/content/6.deployment/presets/99.custom.md

@@ -0,0 +1,46 @@
+# Custom build preset (advanced)
+
+ - Allows full customization
+ - This is an advanced usage pattern
+
+### 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
+
+You can define everything that a custom preset would configure directly in the Nitro options:
+
+```ts [nuxt.config.js]
+export default {
+  nitro: {
+    //
+  }
+}
+```
+
+#### Reusable preset
+
+You can also define a preset in a separate file (or publish as a separate npm package).
+
+```ts [my-preset/index.ts]
+import type { NitroPreset } from '@nuxt/nitro'
+
+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]
+import { resolve } from 'path'
+
+export default {
+  nitro: {
+    preset: resolve(__dirname, 'my-preset')
+  }
+}
+```

docs/content/6.deployment/presets/lambda.md

@@ -0,0 +1,16 @@
+# Lambda function
+
+ - Compatible with common lambda formats (AWS, Netlify and others)
+
+### 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).
+
+It can be used programmatically or as part of a deploy.
+
+```ts
+import { handler } from './.output/server'
+
+// Use programmatically
+const { statusCode, headers, body } = handler({ path: '/' })
+```

docs/content/6.deployment/presets/node.md

@@ -0,0 +1,37 @@
+# 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
+
+### Entrypoint
+
+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.
+
+**Warning**
+It is not recommended to use this preset directly, and particularly not with a 3rd-party server.
+
+### Example
+
+#### Express middleware
+
+```ts
+import express from 'express'
+import handler from './.output/server'
+
+const app = express()
+
+app.use(handler)
+app.listen(3000)
+```
+
+#### Node server
+
+```ts
+import { createServer } from 'http'
+import handler from './.output/server'
+
+const server = createServer(handler)
+server.listen(8080)
+```
+

docs/content/6.deployment/presets/server.md

@@ -0,0 +1,20 @@
+# Node.js server
+
+ - Default preset if none is specified or auto-detected
+ - Loads only the chunks required to render the request for optimal cold start timing
+ - Useful for debugging
+
+### Entrypoint
+
+With `{ preset: 'server' }` the result will be an entrypoint that launches a ready-to-run Node server.
+
+#### Example
+
+```bash
+node .output/server
+# > Load chunks/nitro/server (10.405923ms)
+# > Cold Start (26.289817ms)
+# Listening on http://localhost:3000
+
+curl http://localhost:3000
+```

docs/content/6.deployment/presets/service-worker.md

@@ -0,0 +1,14 @@
+# Service worker
+
+ - Can be used for edge rendering
+ - No dependency on Node.js
+ - No Node.js environment and features
+
+**Warning**
+Deployment as service worker has some limitations since SSR code is not running in Node.js environment but pure JavaScript.
+
+### Entrypoint
+
+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`.
+
+For more information you can see the [source code](https://github.com/nuxt/nitro/blob/main/src/runtime/entries/service-worker.ts).