@depup/nitro 3.0.260311-beta-depup.0

package/skills/nitro/docs/deploy/providers/github-pages.md

@@ -0,0 +1,68 @@
+# GitHub Pages
+
+> Deploy Nitro apps to GitHub Pages.
+
+**Preset:** `github_pages`
+
+<read-more></read-more>
+
+## Setup
+
+Follow the steps to [create a GitHub Pages site](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site).
+
+## Deployment
+
+Here is an example GitHub Actions workflow to deploy your site to GitHub Pages using the `github_pages` preset:
+
+```yaml [.github/workflows/deploy.yml]
+# https://github.com/actions/deploy-pages#usage
+name: Deploy to GitHub Pages
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - run: corepack enable
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "18"
+
+      - run: npx nypm install
+      - run: npm run build
+        env:
+          NITRO_PRESET: github_pages
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: ./.output/public
+
+  # Deployment job
+  deploy:
+    # Add a dependency to the build job
+    needs: build
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github_pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    # Specify runner + deployment step
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1
+```

package/skills/nitro/docs/deploy/providers/gitlab-pages.md

@@ -0,0 +1,37 @@
+# GitLab Pages
+
+> Deploy Nitro apps to GitLab Pages.
+
+**Preset:** `gitlab_pages`
+
+<read-more></read-more>
+
+## Setup
+
+Follow the steps to [create a GitLab Pages site](https://docs.gitlab.com/ee/user/project/pages/#getting-started).
+
+## Deployment
+
+1. Here is an example GitLab Pages workflow to deploy your site to GitLab Pages:
+
+```yaml [.gitlab-ci.yml]
+image: node:lts
+before_script:
+  - npx nypm install
+pages:
+  cache:
+    paths:
+      - node_modules/
+  variables:
+    NITRO_PRESET: gitlab_pages
+  script:
+    - npm run build
+  artifacts:
+    paths:
+      - .output/public
+  publish: .output/public
+  rules:
+    # This ensures that only pushes to the default branch
+    # will trigger a pages deploy
+    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
+```

package/skills/nitro/docs/deploy/providers/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/skills/nitro/docs/deploy/providers/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 { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+  // 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/skills/nitro/docs/deploy/providers/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/skills/nitro/docs/deploy/providers/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/skills/nitro/docs/deploy/providers/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/skills/nitro/docs/deploy/providers/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/skills/nitro/docs/deploy/providers/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)

package/skills/nitro/docs/deploy/providers/vercel.md

@@ -0,0 +1,179 @@
+# Vercel
+
+> Deploy Nitro apps to Vercel.
+
+**Preset:** `vercel`
+
+<read-more></read-more>
+
+<note>
+
+Integration with this provider is possible with [zero configuration](/deploy/#zero-config-providers).
+</note>
+
+## Getting started
+
+Deploying to Vercel comes with the following features:
+
+- [Preview deployments](https://vercel.com/docs/deployments/environments)
+- [Fluid compute](https://vercel.com/docs/fluid-compute)
+- [Observability](https://vercel.com/docs/observability)
+- [Vercel Firewall](https://vercel.com/docs/vercel-firewall)
+And much more. Learn more in [the Vercel documentation](https://vercel.com/docs).
+
+### Deploy with Git
+
+Vercel supports Nitro with zero-configuration. [Deploy Nitro to Vercel now](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fvercel%2Ftree%2Fmain%2Fexamples%2Fnitro).
+
+## API routes
+
+Nitro `/api` directory isn't compatible with Vercel. Instead, you should use:
+
+- `routes/api/` for standalone usage
+
+## Bun runtime
+<read-more></read-more>
+
+You can use [Bun](https://bun.com) instead of Node.js by specifying the runtime using the `vercel.functions` key inside `nitro.config`:
+
+```ts [nitro.config.ts]
+export default defineNitroConfig({
+  vercel: {
+    functions: {
+      runtime: "bun1.x"
+    }
+  }
+})
+```
+
+Alternatively, Nitro also detects Bun automatically if you specify a `bunVersion` property in your `vercel.json`:
+
+```json [vercel.json]
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "bunVersion": "1.x"
+}
+```
+
+## Proxy route rules
+
+Nitro automatically optimizes `proxy` route rules on Vercel by generating [CDN-level rewrites](https://vercel.com/docs/rewrites) at build time. This means matching requests are proxied at the edge without invoking a serverless function, reducing latency and cost.
+
+```ts [nitro.config.ts]
+export default defineNitroConfig({
+  routeRules: {
+    // Proxied at CDN level — no function invocation
+    "/api/**": {
+      proxy: "https://api.example.com/**",
+    },
+  },
+});
+```
+
+### When CDN rewrites apply
+
+A proxy rule is offloaded to a Vercel CDN rewrite when **all** of the following are true:
+
+- The target is an **external URL** (starts with `http://` or `https://`).
+- No advanced `ProxyOptions` are set on the rule.
+
+### Fallback to runtime proxy
+When the proxy rule uses any of the following `ProxyOptions`, Nitro keeps it as a runtime proxy handled by the serverless function:
+
+- `headers` — custom headers on the outgoing request to the upstream
+- `forwardHeaders` / `filterHeaders` — header filtering
+- `fetchOptions` — custom fetch options
+- `cookieDomainRewrite` / `cookiePathRewrite` — cookie manipulation
+- `onResponse` — response callback
+
+<note>
+
+Response headers defined on the route rule via the `headers` option are still applied to CDN-level rewrites. Only request-level `ProxyOptions.headers` (sent to the upstream) require a runtime proxy.
+</note>
+
+## Scheduled tasks (Cron Jobs)
+
+<read-more></read-more>
+
+Nitro automatically converts your [`scheduledTasks`](/docs/tasks#scheduled-tasks) configuration into [Vercel Cron Jobs](https://vercel.com/docs/cron-jobs) at build time. Define your schedules in your Nitro config and deploy - no manual `vercel.json` cron configuration required.
+
+```ts [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+  experimental: {
+    tasks: true
+  },
+  scheduledTasks: {
+    // Run `cms:update` every hour
+    '0 * * * *': ['cms:update'],
+    // Run `db:cleanup` every day at midnight
+    '0 0 * * *': ['db:cleanup']
+  }
+})
+```
+
+### Secure cron job endpoints
+
+<read-more></read-more>
+
+To prevent unauthorized access to the cron handler, set a `CRON_SECRET` environment variable in your Vercel project settings. When `CRON_SECRET` is set, Nitro validates the `Authorization` header on every cron invocation.
+
+## Custom build output configuration
+
+You can provide additional [build output configuration](https://vercel.com/docs/build-output-api/v3) using `vercel.config` key inside `nitro.config`. It will be merged with built-in auto-generated config.
+
+## On-Demand incremental static regeneration (ISR)
+
+On-demand revalidation allows you to purge the cache for an ISR route whenever you want, foregoing the time interval required with background revalidation.
+
+To revalidate a page on demand:
+
+1. Create an Environment Variable which will store a revalidation secret
+  - You can use the command `openssl rand -base64 32` or [Generate a Secret](https://generate-secret.vercel.app/32) to generate a random value.
+
+- Update your configuration:
+
+  ```ts [nitro.config.ts]
+  import { defineNitroConfig } from "nitro/config";
+
+  export default defineNitroConfig({
+    vercel: {
+      config: {
+        bypassToken: process.env.VERCEL_BYPASS_TOKEN
+      }
+    }
+  })
+  ```
+
+- To trigger "On-Demand Incremental Static Regeneration (ISR)" and revalidate a path to a Prerender Function, make a GET or HEAD request to that path with a header of x-prerender-revalidate: `bypassToken`. When that Prerender Function endpoint is accessed with this header set, the cache will be revalidated. The next request to that function should return a fresh response.
+
+
+### Fine-grained ISR config via route rules
+
+By default, query params affect cache keys but are not passed to the route handler unless specified.
+
+You can pass an options object to `isr` route rule to configure caching behavior.
+
+- `expiration`: Expiration time (in seconds) before the cached asset will be re-generated by invoking the Serverless Function. Setting the value to `false` (or `isr: true` route rule) means it will never expire.
+- `group`: Group number of the asset. Prerender assets with the same group number will all be re-validated at the same time.
+- `allowQuery`: List of query string parameter names that will be cached independently.  - If an empty array, query values are not considered for caching.
+  - If `undefined` each unique query value is cached independently.
+  - For wildcard `/**` route rules, `url` is always added
+
+- `passQuery`: When `true`, the query string will be present on the `request` argument passed to the invoked function. The `allowQuery` filter still applies.
+- `exposeErrBody`: When `true`, expose the response body regardless of status code including error status codes. (default `false`
+
+```ts
+export default defineNitroConfig({
+  routeRules: {
+    "/products/**": {
+      isr: {
+        allowQuery: ["q"],
+        passQuery: true,
+        exposeErrBody: true
+      },
+    },
+  },
+});
+```

package/skills/nitro/docs/deploy/providers/zeabur.md

@@ -0,0 +1,19 @@
+# Zeabur
+
+> Deploy Nitro apps to [Zeabur](https://zeabur.com).
+
+**Preset:** `zeabur`
+
+<read-more></read-more>
+
+<note>
+
+Integration with this provider is possible with [zero configuration](/deploy/#zero-config-providers).
+</note>
+
+## Deploy using git
+
+1. Push your code to your git repository (Currently only GitHub supported).
+2. [Import your project](https://zeabur.com/docs/get-started) into Zeabur.
+3. Zeabur will detect that you are using Nitro and will enable the correct settings for your deployment.
+4. Your application is deployed!