nitro-nightly 3.0.1-alpha.2 → 3.0.260415-beta

package/dist/docs/1.deploy/2.providers/21.vercel.md

@@ -0,0 +1,270 @@
+# 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 defineConfig({
+  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"
+}
+```
+
+## Per-route function configuration
+
+Use `vercel.functionRules` to override [serverless function settings](https://vercel.com/docs/build-output-api/primitives#serverless-function-configuration) for specific routes. Each key is a route pattern and its value is a partial function configuration object that gets merged with the base `vercel.functions` config. Note: array properties (e.g., `regions`) from route config will replace the base config arrays rather than merging them.
+
+This is useful when certain routes need different resource limits, regions, or features like [Vercel Queues triggers](https://vercel.com/docs/queues).
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  vercel: {
+    functionRules: {
+      "/api/heavy-computation": {
+        maxDuration: 800,
+        memory: 4096,
+      },
+      "/api/regional": {
+        regions: ["lhr1", "cdg1"],
+      },
+      "/api/queues/process-order": {
+        experimentalTriggers: [{ type: "queue/v2beta", topic: "orders" }],
+      },
+    },
+  },
+});
+```
+
+Route patterns support wildcards via [rou3](https://github.com/h3js/rou3) matching (e.g., `/api/slow/**` matches all routes under `/api/slow/`).
+
+## 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 defineConfig({
+  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 { defineConfig } from "nitro";
+
+export default defineConfig({
+  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.
+
+## Queues
+
+<read-more></read-more>
+
+Nitro integrates with [Vercel Queues](https://vercel.com/docs/queues) to process messages asynchronously. Define your queue topics in the Nitro config and handle incoming messages with the `vercel:queue` runtime hook.
+
+```ts [nitro.config.ts]
+export default defineNitroConfig({
+  vercel: {
+    queues: {
+      triggers: [
+        // Only `topic` is required
+        { topic: "notifications" },
+        { topic: "orders", retryAfterSeconds: 60, initialDelaySeconds: 5 },
+      ],
+    },
+  },
+});
+```
+
+### Handling messages
+
+Use the `vercel:queue` hook in a [Nitro plugin](/guide/plugins) to process incoming queue messages:
+
+```ts [server/plugins/queues.ts]
+export default defineNitroPlugin((nitro) => {
+  nitro.hooks.hook("vercel:queue", ({ message, metadata, send }) => {
+    console.log(`[${metadata.topicName}] Message ${metadata.messageId}:`, message);
+  });
+});
+```
+
+### Running tasks from queue messages
+
+You can use queue messages to trigger [Nitro tasks](/docs/tasks):
+
+```ts [server/plugins/queues.ts]
+import { runTask } from "nitro/task";
+
+export default defineNitroPlugin((nitro) => {
+  nitro.hooks.hook("vercel:queue", async ({ message, metadata }) => {
+    if (metadata.topicName === "orders") {
+      await runTask("orders:fulfill", { payload: message });
+    }
+  });
+});
+```
+
+### Sending messages
+
+Use the `@vercel/queue` package directly to send messages to a topic:
+
+```ts [server/routes/api/orders.post.ts]
+import { send } from "@vercel/queue";
+
+export default defineEventHandler(async (event) => {
+  const order = await event.req.json();
+  const { messageId } = await send("orders", order);
+  return { messageId };
+});
+```
+
+## 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 { defineConfig } from "nitro";
+
+  export default defineConfig({
+    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 defineConfig({
+  routeRules: {
+    "/products/**": {
+      isr: {
+        allowQuery: ["q"],
+        passQuery: true,
+        exposeErrBody: true
+      },
+    },
+  },
+});
+```

package/dist/docs/1.deploy/2.providers/22.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!

package/dist/docs/1.deploy/2.providers/23.zephyr.md

@@ -0,0 +1,99 @@
+# Zephyr Cloud
+
+> Deploy Nitro apps to [Zephyr Cloud](https://zephyr-cloud.io).
+
+**Preset:** `zephyr`
+
+<read-more></read-more>
+
+Zephyr support is built into Nitro through the `zephyr` preset.
+
+For most Zephyr-specific topics such as BYOC, cloud integrations, environments, and CI/CD authentication, refer to the [Zephyr Cloud docs](https://docs.zephyr-cloud.io).
+
+<note>
+
+Zephyr is a little different from most Nitro deployment providers. Instead of targeting a single hosting vendor directly, Zephyr acts as a deployment control plane on top of either Zephyr-managed infrastructure or your own cloud integrations.
+</note>
+
+## BYOC model
+
+Zephyr supports a BYOC (Bring Your Own Cloud) model. In Zephyr's architecture, the control plane stays managed by Zephyr, while the data plane (workers and storage) runs in your cloud accounts.
+
+This lets you keep Zephyr's deployment workflow while using any supported Zephyr cloud integration. See the [Zephyr BYOC docs](https://docs.zephyr-cloud.io/features/byoc) for the current list of supported providers.
+
+## Deploy with Nitro CLI
+
+Use Nitro's deploy command to build and upload your app to Zephyr in one step:
+
+```bash
+npx nitro deploy --preset zephyr
+```
+
+Nitro will upload the generated output using `zephyr-agent`. If `zephyr-agent` is missing, Nitro will prompt to install it locally and will install it automatically in CI.
+
+## Deploy during build
+
+Zephyr is a little different here from most Nitro providers: we recommend enabling deployment during `nitro build` and treating build as the primary deployment step.
+
+If your CI pipeline already runs `nitro build`, enable deployment during the build step:
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  preset: "zephyr",
+  zephyr: {
+    deployOnBuild: true,
+  },
+});
+```
+
+Then your normal build command is enough:
+
+<pm-run></pm-run>
+
+After the build finishes, Nitro uploads the generated output to Zephyr, deploys it to the edge, and prints the deployment URL:
+
+```txt
+◐ Building [Nitro] (preset: zephyr, compatibility: YYYY-MM-DD)
+...
+ZEPHYR   Uploaded local snapshot in 110ms
+ZEPHYR   Deployed to Zephyr's edge in 700ms.
+ZEPHYR
+ZEPHYR   https://my-app.zephyrcloud.app
+```
+
+## CI authentication
+
+Zephyr requires an API token for non-interactive deployments. The example below uses the simpler personal-token style setup with `ZE_SECRET_TOKEN` together with `zephyr.deployOnBuild`.
+
+```yaml [.github/workflows/deploy.yml]
+name: Deploy with Zephyr
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    env:
+      ZE_SECRET_TOKEN: ${{ secrets.ZEPHYR_AUTH_TOKEN }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm run build
+```
+
+For more advanced CI/CD setups, Zephyr also documents organization-level server-token authentication using `ZE_SERVER_TOKEN`. See the [Zephyr CI/CD server token docs](https://docs.zephyr-cloud.io/features/ci-cd-server-token).
+
+## Options
+
+### `zephyr.deployOnBuild`
+
+Deploy to Zephyr during `nitro build` when using the `zephyr` preset.
+
+- Default: `false`

package/dist/docs/1.deploy/2.providers/24.zerops.md

@@ -0,0 +1,102 @@
+# Zerops
+
+> Deploy Nitro apps to [Zerops](https://zerops.io).
+
+**Preset:** `zerops`
+
+<read-more></read-more>
+
+> [!IMPORTANT]
+> 🚧 This preset is currently experimental.
+
+Zerops supports deploying both static and server-side rendered apps with a simple configuration file in your project root.
+
+## Starter templates
+
+If you want to quckly get started with zerops and nitro you can use repositories [`zeropsio/recipe-nitro-nodejs`](https://github.com/zeropsio/recipe-nitro-nodejs) and [`zeropsio/recipe-nitro-static`](https://github.com/zeropsio/recipe-nitro-static) starter templates.
+
+## Project setup
+
+Projects and services can be added either through [project add wizard](https://app.zerops.io/dashboard/project-add) or imported using `zerops-project-import.yml`.
+
+<code-group>
+
+```yml [zerops-project-import.yml (node.js)]
+project:
+  name: nitro-app
+
+services:
+  - hostname: app
+    type: nodejs@20
+```
+
+```yml [zerops-project-import.yml (static)]
+project:
+  name: nitro-app
+
+services:
+  - hostname: app
+    type: static
+```
+</code-group>
+
+Then create a `zerops.yml` config in your project root:
+
+<code-group>
+
+```yml [zerops.yml (node.js)]
+zerops:
+  - setup: app
+    build:
+      base: nodejs@20
+      envVariables:
+        NITRO_PRESET: zerops
+      buildCommands:
+        - pnpm i
+        - pnpm run build
+      deployFiles:
+        - .output
+        - package.json
+        - node_modules
+    run:
+      base: nodejs@20
+      ports:
+        - port: 3000
+          httpSupport: true
+      start: node .output/server/index.mjs
+```
+
+```yml [zerops.yml (static)]
+zerops:
+  - setup: app
+    build:
+      base: nodejs@20
+      envVariables:
+        NITRO_PRESET: zerops-static
+      buildCommands:
+        - pnpm i
+        - pnpm build
+      deployFiles:
+        - .zerops/output/static/~
+    run:
+      base: static
+```
+</code-group>
+
+Now you can trigger the [build & deploy pipeline using the Zerops CLI](#building-deploying-your-app) or by connecting the app service with your [GitHub](https://docs.zerops.io/references/github-integration/) / [GitLab](https://docs.zerops.io/references/gitlab-integration) repository from inside the service detail.
+
+## Build and deploy
+
+Open [Settings > Access Token Management](https://app.zerops.io/settings/token-management) in the Zerops app and generate a new access token.
+
+Log in using your access token with the following command:
+
+<pm-x></pm-x>
+
+Navigate to the root of your app (where `zerops.yml` is located) and run the following command to trigger the deploy:
+
+<pm-x></pm-x>
+
+Your code can be deployed automatically on each commit or a new tag by connecting the service with your [GitHub](https://docs.zerops.io/references/gitlab-integration) / [GitLab](https://docs.zerops.io/references/gitlab-integration) repository. This connection can be set up in the service detail.
+
+<read-more></read-more>

package/dist/docs/1.deploy/2.providers/3.azure.md

@@ -0,0 +1,72 @@
+# Azure
+
+> Deploy Nitro apps to Azure Static Web apps or functions.
+
+## Azure static web apps
+
+**Preset:** `azure-swa`
+
+<read-more></read-more>
+
+<note>
+
+Integration with this provider is possible with [zero configuration](/deploy/#zero-config-providers).
+</note>
+
+[Azure Static Web Apps](https://azure.microsoft.com/en-us/products/app-service/static) 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
+
+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 to preview before deploying.
+
+```bash
+NITRO_PRESET=azure npx nypm@latest build
+npx @azure/static-web-apps-cli start .output/public --api-location .output/server
+```
+
+### Configuration
+
+Azure Static Web Apps are [configured](https://learn.microsoft.com/en-us/azure/static-web-apps/configuration) using the `staticwebapp.config.json` file.
+
+Nitro automatically generates this configuration file whenever the application is built with the `azure` preset.
+
+Nitro will automatically add the following properties based on the following criteria:
+| Property | Criteria | Default |
+| --- | --- | --- |
+| **[platform.apiRuntime](https://learn.microsoft.com/en-us/azure/static-web-apps/configuration#platform)** | Will automatically set to `node:16` or `node:14` depending on your package configuration. | `node:16` |
+| **[navigationFallback.rewrite](https://learn.microsoft.com/en-us/azure/static-web-apps/configuration#fallback-routes)** | Is always `/api/server` | `/api/server` |
+| **[routes](https://learn.microsoft.com/en-us/azure/static-web-apps/configuration#routes)** | All prerendered routes are added. Additionally, if you do not have an `index.html` file an empty one is created for you for compatibility purposes and also requests to `/index.html` are redirected to the root directory which is handled by `/api/server`.  | `[]` |
+
+### Custom configuration
+
+You can alter the Nitro generated configuration using `azure.config` option.
+
+Custom routes will be added and matched first. In the case of a conflict (determined if an object has the same route property), custom routes will override generated ones.
+
+### 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:
+
+```yaml [.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 ######
+```
+
+That's it! Now Azure Static Web Apps will automatically deploy your Nitro-powered application on push.
+
+If you are using runtimeConfig, you will likely want to configure the corresponding [environment variables on Azure](https://docs.microsoft.com/en-us/azure/static-web-apps/application-settings).

package/dist/docs/1.deploy/2.providers/4.cleavr.md

@@ -0,0 +1,33 @@
+# Cleavr
+
+> Deploy Nitro apps to Cleavr.
+
+**Preset:** `cleavr`
+
+<read-more></read-more>
+
+<note>
+
+Integration with this provider is possible with [zero configuration](/deploy/#zero-config-providers).
+</note>
+
+## Set up your web app
+
+In your project, set Nitro preset to `cleavr`.
+
+```js
+export default {
+  nitro: {
+    preset: 'cleavr'
+  }
+}
+```
+
+Push changes to your code repository.
+
+**In your Cleavr panel:**
+
+1. Provision a new server
+2. Add a website, selecting **Nuxt 3** as the app type
+3. In web app > settings > Code Repo, point to your project's code repository
+You're now all set to deploy your project!