nitro 3.0.1-alpha.2 → 3.0.260415-beta

package/dist/docs/1.deploy/2.providers/14.heroku.md

@@ -0,0 +1,84 @@
+# Heroku
+
+> Deploy Nitro apps to Heroku.
+
+**Preset:** `heroku`
+
+<read-more></read-more>
+
+## Using the heroku CLI
+
+1. Create a new Heroku app.
+
+  ```bash
+  heroku create myapp
+  ```
+
+2. Configure Heroku to use the nodejs buildpack.
+
+  ```bash
+  heroku buildpacks:set heroku/nodejs
+  ```
+
+3. Configure your app.
+
+  ```bash
+  heroku config:set NITRO_PRESET=heroku
+  ```
+
+4. Ensure you have `start` and `build` commands in your `package.json` file.
+
+  ```json5
+  "scripts": {
+    "build": "nitro build", // or `nuxt build` if using nuxt
+    "start": "node .output/server/index.mjs"
+  }
+  ```
+
+
+## With nginx
+
+1. Add the heroku Nginx buildpack [here](https://github.com/heroku/heroku-buildpack-nginx.git)
+
+2. Change to the 'node' preset in your `nitro.config`
+
+  ```json5
+  "nitro": {
+     "preset":"node",
+  }
+  ```
+
+3. From the **Existing app** section of buildpack doc, 2 key steps are required to get things running
+
+  Step 1: Listen on a socket at 'tmp/nginx.socket'
+  Step 2: Create a file '/tmp/app-initialized' when your app is ready to accept connections
+
+4. Create custom app runner, eg: apprunner.mjs at the root of the project (or any other preferred location), in this file, create a server, using the listener generated by the node preset, then listen on the socket as detailed in the buildpack doc
+
+  ```ts
+  import { createServer } from 'node:http'
+  import { listener } from './.output/server/index.mjs'
+
+  const server = createServer(listener)
+
+  server.listen('/tmp/nginx.socket') //following the buildpack doc
+  ```
+
+5. To create the 'tmp/app-initialized' file, use a nitro plugin, create file 'initServer.ts' at the root of the project (or any other preferred location)
+
+  ```ts
+  import fs from "fs"
+
+  export default definePlugin((nitroApp) => {
+     if((process.env.NODE_ENV || 'development') != 'development') {
+        fs.openSync('/tmp/app-initialized', 'w')
+     }
+  })
+  ```
+
+6. Finally, create file 'Procfile' at the root of the project, with the Procfile, we tell heroku to start nginx and use the custom apprunner.mjs to start the server
+
+  web: bin/start-nginx node apprunner.mjs
+
+7. Bonus: create file 'config/nginx.conf.erb' to customize your nginx config. With the node preset, by default, static files handlers will not be generated, you can use nginx to server static files, just add the right location rule to the server block(s), or, force the node preset to generate handlers for the static files by setting serveStatic to true.
+

package/dist/docs/1.deploy/2.providers/15.iis.md

@@ -0,0 +1,38 @@
+# IIS
+
+> Deploy Nitro apps to IIS.
+
+## Using [IISnode](https://github.com/Azure/iisnode)
+
+**Preset:** `iis_node`
+
+1. Install the latest LTS version of [Node.js](https://nodejs.org/en/) on your Windows Server.
+2. Install [IISnode](https://github.com/azure/iisnode/releases)
+3. Install [IIS `URLRewrite` Module](https://www.iis.net/downloads/microsoft/url-rewrite).
+4. In IIS, add `.mjs` as a new mime type and set its content type to `application/javascript`.
+5. Deploy the contents of your `.output` folder to your website in IIS.
+
+## Using IIS handler
+**Preset:** `iis_handler`
+
+You can use IIS http handler directly.
+
+1. Install the latest LTS version of [Node.js](https://nodejs.org/en/) on your Windows Server.
+2. Install [IIS `HttpPlatformHandler` Module](https://www.iis.net/downloads/microsoft/httpplatformhandler)
+3. Copy your `.output` directory into the Windows Server, and create a website on IIS pointing to that exact directory.
+
+## IIS config options
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  // IIS options default
+  iis: {
+    // merges in a pre-existing web.config file to the nitro default file
+    mergeConfig: true,
+    // overrides the default nitro web.config file all together
+    overrideConfig: false,
+  },
+});
+```

package/dist/docs/1.deploy/2.providers/16.koyeb.md

@@ -0,0 +1,109 @@
+# Koyeb
+
+> Deploy Nitro apps to Koyeb.
+
+**Preset:** `koyeb`
+
+<read-more></read-more>
+
+## Using the control panel
+
+1. In the [Koyeb control panel](https://app.koyeb.com/), click **Create App**.
+
+2. Choose **GitHub** as your deployment method.
+
+3. Choose the GitHub **repository** and **branch** containing your application code.
+
+4. Name your Service.
+
+5. If you did not add a `start` command to your `package.json` file, under the **Build and deployment settings**, toggle the override switch associated with the run command field.  In the **Run command** field, enter:
+
+  ```bash
+  node .output/server/index.mjs`
+  ```
+
+6. In the **Advanced** section, click **Add Variable** and add a `NITRO_PRESET` variable set to `koyeb`.
+
+7. Name the App.
+
+8. Click the **Deploy** button.
+
+
+## Using the Koyeb CLI
+
+1. Follow the instructions targeting your operating system to [install the Koyeb CLI client](https://www.koyeb.com/docs/cli/installation) with an installer.  Alternatively, visit the [releases page on GitHub](https://github.com/koyeb/koyeb-cli/releases) to directly download required files.
+
+2. Create a Koyeb API access token by visiting the [API settings for your organization](https://app.koyeb.com/settings/api) in the Koyeb control panel.
+
+3. Log into your account with the Koyeb CLI by typing:
+
+  ```bash
+  koyeb login
+  ```
+
+  Paste your API credentials when prompted.
+
+4. Deploy your Nitro application from a GitHub repository with the following command.  Be sure to substitute your own values for `<APPLICATION_NAME>`, `<YOUR_GITHUB_USERNAME>`, and `<YOUR_REPOSITORY_NAME>`:
+
+  ```bash
+  koyeb app init <APPLICATION_NAME> \
+     --git github.com/<YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME> \
+     --git-branch main \
+     --git-run-command "node .output/server/index.mjs" \
+     --ports 3000:http \
+     --routes /:3000 \
+     --env PORT=3000 \
+     --env NITRO_PRESET=koyeb
+  ```
+
+
+## Using a docker container
+
+1. Create a `.dockerignore` file in the root of your project and add the following lines:
+
+  ```
+  Dockerfile
+  .dockerignore
+  node_modules
+  npm-debug.log
+  .nitro
+  .output
+  .git
+  dist
+  README.md
+  ```
+
+2. Add a `Dockerfile` to the root of your project:
+
+  ```
+  FROM node:18-alpine AS base
+
+  FROM base AS deps
+  RUN apk add --no-cache libc6-compat
+  WORKDIR /app
+  COPY package.json package-lock.json ./
+  RUN npm ci
+
+  FROM base AS builder
+  WORKDIR /app
+  COPY --from=deps /app/node_modules ./node_modules
+  COPY . .
+  RUN npm run build && npm cache clean --force
+
+  FROM base AS runner
+  WORKDIR /app
+  RUN addgroup --system --gid 1001 nodejs
+  RUN adduser --system --uid 1001 nitro
+  COPY --from=builder /app .
+  USER nitro
+  EXPOSE 3000
+  ENV PORT 3000
+  CMD ["npm", "run", "start"]
+  ```
+
+
+The Dockerfile above provides the minimum requirements to run the Nitro application. You can easily extend it depending on your needs.
+You will then need to push your Docker image to a registry. You can use [Docker Hub](https://hub.docker.com/) or [GitHub Container Registry](https://docs.github.com/en/packages/guides/about-github-container-registry) for example.
+In the Koyeb control panel, use the image and the tag field to specify the image you want to deploy.
+You can also use the [Koyeb CLI](https://www.koyeb.com/docs/build-and-deploy/cli/installation)
+Refer to the Koyeb [Docker documentation](https://www.koyeb.com/docs/build-and-deploy/prebuilt-docker-images) for more information.

package/dist/docs/1.deploy/2.providers/17.netlify.md

@@ -0,0 +1,47 @@
+# Netlify
+
+> Deploy Nitro apps to Netlify functions or edge.
+
+**Preset:** `netlify`
+
+<read-more></read-more>
+
+<note>
+
+Integration with this provider is possible with [zero configuration](/deploy/#zero-config-providers).
+</note>
+
+Normally, the deployment to Netlify does not require any configuration.
+Nitro will auto-detect that you are in a [Netlify](https://www.netlify.com) build environment and build the correct version of your server.
+
+For new sites, Netlify will detect that you are using Nitro and set the publish directory to `dist` and build command to `npm run build`.
+
+If you are upgrading an existing site you should check these and update them if needed.
+
+If you want to add custom redirects, you can do so with [`routeRules`](/config#routerules) or by adding a [`_redirects`](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file) file to your `public` directory.
+
+For deployment, just push to your git repository [as you would normally do for Netlify](https://docs.netlify.com/configure-builds/get-started/).
+
+<note>
+
+Make sure the publish directory is set to `dist` when creating a new project.
+</note>
+
+## Netlify edge functions
+
+**Preset:** `netlify_edge`
+
+Netlify Edge Functions use Deno and the powerful V8 JavaScript runtime to let you run globally distributed functions for the fastest possible response times.
+
+<read-more></read-more>
+
+Nitro output can directly run the server at the edge. Closer to your users.
+
+<note>
+
+Make sure the publish directory is set to `dist` when creating a new project.
+</note>
+
+## Custom deploy configuration
+
+You can provide additional deploy configuration using the `netlify` key inside `nitro.config`. It will be merged with built-in auto-generated config. Currently the only supported value is `images.remote_images`, for [configuring Netlify Image CDN](https://docs.netlify.com/image-cdn/create-integration/).

package/dist/docs/1.deploy/2.providers/18.platform-sh.md

@@ -0,0 +1,37 @@
+# Platform.sh
+
+> Deploy Nitro apps to platform.sh
+
+**Preset:** `platform_sh`
+
+<read-more></read-more>
+
+## Setup
+
+First, create a new project on platform.sh and link it to the repository you want to auto-deploy with.
+
+Then in repository create `.platform.app.yaml` file:
+
+```yaml [.platform.app.yaml]
+name: nitro-app
+type: 'nodejs:20'
+disk: 128
+web:
+  commands:
+    start: "node .output/server/index.mjs"
+build:
+  flavor: none
+hooks:
+  build: |
+    corepack enable
+    npx nypm install
+    NITRO_PRESET=platform_sh npm run build
+mounts:
+    '.data':
+        source: local
+        source_path: .data
+```
+
+<read-more></read-more>
+
+<read-more></read-more>

package/dist/docs/1.deploy/2.providers/19.render.md

@@ -0,0 +1,37 @@
+# Render.com
+
+> Deploy Nitro apps to Render.com.
+
+**Preset:** `render_com`
+
+<read-more></read-more>
+
+## Set up application
+
+1. [Create a new Web Service](https://dashboard.render.com/select-repo?type=web) and select the repository that contains your code.
+2. Ensure the 'Node' environment is selected.
+3. Update the start command to `node .output/server/index.mjs`
+4. Click 'Advanced' and add an environment variable with `NITRO_PRESET` set to `render_com`. You may also need to add a `NODE_VERSION` environment variable set to `20` for the build to succeed ([docs](https://render.com/docs/node-version)).
+5. Click 'Create Web Service'.
+
+## Infrastructure as Code (IaC)
+
+1. Create a file called `render.yaml` with following content at the root of your repository.
+
+This file followed by [Infrastructure as Code](https://render.com/docs/infrastructure-as-code) on Render
+
+```yaml
+services:
+  - type: web
+    name: <PROJECTNAME>
+    env: node
+    branch: main
+    startCommand: node .output/server/index.mjs
+    buildCommand: npx nypm install && npm run build
+    envVars:
+    - key: NITRO_PRESET
+      value: render_com
+```
+
+1. [Create a new Blueprint Instance](https://dashboard.render.com/select-repo?type=blueprint) and select the repository containing your `render.yaml` file.
+You should be good to go!

package/dist/docs/1.deploy/2.providers/2.aws-amplify.md

@@ -0,0 +1,81 @@
+# AWS Amplify
+
+> Deploy Nitro apps to AWS Amplify Hosting.
+
+**Preset:** `aws_amplify`
+
+<read-more></read-more>
+
+## Deploy to AWS Amplify Hosting
+
+<tip>
+
+Integration with this provider is possible with [zero configuration](/deploy/#zero-config-providers).
+</tip>
+
+1. Login to the [AWS Amplify Hosting Console](https://console.aws.amazon.com/amplify/)
+2. Click on "Get Started" > Amplify Hosting (Host your web app)
+3. Select and authorize access to your Git repository provider and select the main branch
+4. Choose a name for your app, make sure build settings are auto-detected and optionally set requirement environment variables under the advanced section
+5. Optionally, select Enable SSR logging to enable server-side logging to your Amazon CloudWatch account
+6. Confirm configuration and click on "Save and Deploy"
+
+## Advanced Configuration
+You can configure advanced options of this preset using `awsAmplify` option.
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  awsAmplify: {
+      // catchAllStaticFallback: true,
+      // imageOptimization: { path: "/_image", cacheControl: "public, max-age=3600, immutable" },
+      // imageSettings: { ... },
+      // runtime: "nodejs18.x", // default: "nodejs18.x" | "nodejs16.x" | "nodejs20.x"
+  }
+})
+```
+
+### `amplify.yml`
+
+You might need a custom `amplify.yml` file for advanced configuration. Here are two template examples:
+
+<code-group>
+
+```yml [amplify.yml]
+version: 1
+frontend:
+  phases:
+    preBuild:
+      commands:
+        - nvm use 18 && node --version
+        - corepack enable && npx --yes nypm install
+    build:
+      commands:
+        - pnpm build
+  artifacts:
+    baseDirectory: .amplify-hosting
+    files:
+      - "**/*"
+```
+
+```yml [amplify.yml (monorepo)]
+version: 1
+applications:
+  - frontend:
+      phases:
+        preBuild:
+          commands:
+          - nvm use 18 && node --version
+          - corepack enable && npx --yes nypm install
+        build:
+          commands:
+            - pnpm --filter website1 build
+      artifacts:
+        baseDirectory: apps/website1/.amplify-hosting
+        files:
+          - '**/*'
+      buildPath: /
+    appRoot: apps/website1
+```
+</code-group>

package/dist/docs/1.deploy/2.providers/20.stormkit.md

@@ -0,0 +1,24 @@
+# StormKit
+
+> Deploy Nitro apps to StormKit.
+
+**Preset:** `stormkit`
+
+<read-more></read-more>
+
+<note>
+
+Integration with [Stormkit](https://www.stormkit.io/) is possible with [zero configuration](/deploy#zero-config-providers).
+</note>
+
+## Setup
+
+Follow the steps to [create a new app](https://app.stormkit.io/apps/new) on Stormkit.
+
+![Create a new app on Stormkit](/images/stormkit-new-app.png)
+
+## Deployment
+
+By default, Stormkit will deploy your apps automatically when you push changes to your main branch. But to trigger a manual deploy (for example, you might do this for the very first deployment), you may click `Deploy now`.
+
+![Trigger a manual deploy with Deploy Now](/images/stormkit-deploy.png)