@depup/nitro 3.0.260311-beta-depup.0

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

@@ -0,0 +1,375 @@
+# Cloudflare
+
+> Deploy Nitro apps to Cloudflare.
+
+## Cloudflare Workers
+
+**Preset:** `cloudflare_module`
+
+<read-more></read-more>
+
+<note>
+
+Integration with this provider is possible with [zero configuration](/deploy#zero-config-providers) supporting [workers builds (beta)](https://developers.cloudflare.com/workers/ci-cd/builds/).
+</note>
+
+<important>
+
+To use Workers with Static Assets, you need a Nitro compatibility date set to `2024-09-19` or later.
+</important>
+
+The following shows an example `nitro.config.ts` file for deploying a Nitro app to Cloudflare Workers.
+
+```ts [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+    compatibilityDate: "2024-09-19",
+    preset: "cloudflare_module",
+    cloudflare: {
+      deployConfig: true,
+      nodeCompat: true
+    }
+})
+```
+
+By setting `deployConfig: true`, Nitro will automatically generate a `wrangler.json` for you with the correct configuration.
+If you need to add [Cloudflare Workers configuration](https://developers.cloudflare.com/workers/wrangler/configuration/), such as [bindings](https://developers.cloudflare.com/workers/runtime-apis/bindings/), you can either:
+
+- Set these in your Nitro config under the `cloudflare: { wrangler : {} }`. This has the same type as `wrangler.json`.
+- Provide your own `wrangler.json`. Nitro will merge your config with the appropriate settings, including pointing to the build output.
+
+### Local Preview
+You can use [Wrangler](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler) to preview your app locally:
+
+<pm-run></pm-run>
+
+<pm-x></pm-x>
+
+### Manual Deploy
+
+After having built your application you can manually deploy it with Wrangler.
+
+First make sure to be logged into your Cloudflare account:
+
+<pm-x></pm-x>
+
+Then you can deploy the application with:
+
+<pm-x></pm-x>
+
+### Runtime Hooks
+
+You can use [runtime hooks](/docs/plugins#nitro-runtime-hooks) below in order to extend [Worker handlers](https://developers.cloudflare.com/workers/runtime-apis/handlers/).
+
+<read-more></read-more>
+
+- [`cloudflare:scheduled`](https://developers.cloudflare.com/workers/runtime-apis/handlers/scheduled/)
+- [`cloudflare:email`](https://developers.cloudflare.com/email-routing/email-workers/runtime-api/)
+- [`cloudflare:queue`](https://developers.cloudflare.com/queues/configuration/javascript-apis/#consumer)
+- [`cloudflare:tail`](https://developers.cloudflare.com/workers/runtime-apis/handlers/tail/)
+- `cloudflare:trace`
+
+### Additional Exports
+You can add a `exports.cloudflare.ts` file to your project root to export additional handlers or properties to the Cloudflare Worker entrypoint.
+
+```ts [exports.cloudflare.ts]
+export class MyWorkflow extends WorkflowEntrypoint {
+  async run(event: WorkflowEvent, step: WorkflowStep) {
+    // ...
+  }
+}
+```
+
+Nitro will automatically detect this file and include its exports in the final build.
+
+<warning>
+
+The `exports.cloudflare.ts` file must not have a default export.
+</warning>
+
+You can also customize the entrypoint file location using the `cloudflare.exports` option in your `nitro.config.ts`:
+
+```ts [nitro.config.ts]
+export default defineConfig({
+  cloudflare: {
+    exports: "custom-exports-entry.ts"
+  }
+})
+```
+
+### Scheduled Tasks (Cron Triggers)
+
+When using [Nitro tasks](/docs/tasks) with `scheduledTasks`, Nitro automatically generates [Cron Triggers](https://developers.cloudflare.com/workers/configuration/cron-triggers/) in the wrangler config at build time.
+
+```ts [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+  preset: "cloudflare_module",
+  experimental: {
+    tasks: true,
+  },
+  scheduledTasks: {
+    "* * * * *": ["cms:update"],
+    "0 15 1 * *": ["db:cleanup"],
+  },
+  cloudflare: {
+    deployConfig: true,
+  },
+})
+```
+
+No manual Wrangler configuration is needed - Nitro handles it for you.
+
+## Cloudflare Pages
+
+**Preset:** `cloudflare_pages`
+
+<read-more></read-more>
+
+<note>
+
+Integration with this provider is possible with [zero configuration](/deploy#zero-config-providers).
+</note>
+
+<warning>
+
+Cloudflare [Workers Module](#cloudflare-workers) is the new recommended preset for deployments. Please consider using the pages only if you need specific features.
+</warning>
+
+The following shows an example `nitro.config.ts` file for deploying a Nitro app to Cloudflare Pages.
+
+```ts [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+    preset: "cloudflare_pages",
+    cloudflare: {
+      deployConfig: true,
+      nodeCompat:true
+    }
+})
+```
+
+Nitro automatically generates a `_routes.json` file that controls which routes get served from files and which are served from the Worker script. The auto-generated routes file can be overridden with the config option `cloudflare.pages.routes` ([read more](https://developers.cloudflare.com/pages/platform/functions/routing/#functions-invocation-routes)).
+
+### Local Preview
+
+You can use [Wrangler](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler) to preview your app locally:
+
+<pm-run></pm-run>
+
+<pm-x></pm-x>
+
+### Manual Deploy
+
+After having built your application you can manually deploy it with Wrangler, in order to do so first make sure to be
+logged into your Cloudflare account:
+
+<pm-x></pm-x>
+
+Then you can deploy the application with:
+
+<pm-x></pm-x>
+
+## Deploy within CI/CD using GitHub Actions
+
+Regardless on whether you're using Cloudflare Pages or Cloudflare Workers, you can use the [Wrangler GitHub actions](https://github.com/marketplace/actions/deploy-to-cloudflare-workers-with-wrangler) to deploy your application.
+
+<note>
+
+**Note:** Remember to [instruct Nitro to use the correct preset](/deploy#changing-the-deployment-preset) (note that this is necessary for all presets including the `cloudflare_pages` one).
+</note>
+
+## Environment Variables
+
+Nitro allows you to universally access environment variables using `process.env` or `import.meta.env` or the runtime config.
+
+<note>
+
+Make sure to only access environment variables **within the event lifecycle**  and not in global contexts since Cloudflare only makes them available during the request lifecycle and not before.
+</note>
+
+**Example:** If you have set the `SECRET` and `NITRO_HELLO_THERE` environment variables set you can access them in the following way:
+
+```ts
+import { defineHandler } from "nitro";
+import { useRuntimeConfig } from "nitro/runtime-config";
+
+console.log(process.env.SECRET) // note that this is in the global scope! so it doesn't actually work and the variable is undefined!
+
+export default defineHandler((event) => {
+  // note that all the below are valid ways of accessing the above mentioned variables
+  useRuntimeConfig().helloThere
+  useRuntimeConfig().secret
+  process.env.NITRO_HELLO_THERE
+  import.meta.env.SECRET
+});
+```
+
+### Specify Variables in Development Mode
+
+For development, you can use a `.env` or `.env.local` file to specify environment variables:
+
+```ini
+NITRO_HELLO_THERE="captain"
+SECRET="top-secret"
+```
+
+<note>
+
+**Note:** Make sure you add `.env` and `.env.local` to the `.gitignore` file so that you don't commit it as it can contain sensitive information.
+</note>
+
+### Specify Variables for local previews
+
+After build, when you try out your project locally with `wrangler dev` or `wrangler pages dev`, in order to have access to environment variables you will need to specify the in a `.dev.vars` file in the root of your project (as presented in the [Pages](https://developers.cloudflare.com/pages/functions/bindings/#interact-with-your-environment-variables-locally) and [Workers](https://developers.cloudflare.com/workers/configuration/environment-variables/#interact-with-environment-variables-locally) documentation).
+
+If you are using a `.env` or `.env.local` file while developing, your `.dev.vars` should be identical to it.
+
+<note>
+
+**Note:** Make sure you add `.dev.vars` to the `.gitignore` file so that you don't commit it as it can contain sensitive information.
+</note>
+
+### Specify Variables for Production
+
+For production, use the Cloudflare dashboard or the [`wrangler secret`](https://developers.cloudflare.com/workers/wrangler/commands/#secret) command to set environment variables and secrets.
+
+### Specify Variables using `wrangler.toml`/`wrangler.json`
+
+You can specify a custom `wrangler.toml`/`wrangler.json` file and define vars inside.
+
+<warning>
+
+Note that this isn't recommend for sensitive data like secrets.
+</warning>
+
+**Example:**
+
+<code-group>
+
+```ini [wrangler.toml]
+# Shared
+[vars]
+NITRO_HELLO_THERE="general"
+SECRET="secret"
+
+# Override values for `--env production` usage
+[env.production.vars]
+NITRO_HELLO_THERE="captain"
+SECRET="top-secret"
+```
+
+```json [wrangler.json]
+{
+  "vars": {
+    "NITRO_HELLO_THERE": "general",
+    "SECRET": "secret"
+  },
+  "env": {
+    "production": {
+      "vars": {
+        "NITRO_HELLO_THERE": "captain",
+        "SECRET": "top-secret"
+      }
+    }
+  }
+}
+
+```
+</code-group>
+
+## Direct access to Cloudflare bindings
+
+Bindings are what allows you to interact with resources from the Cloudflare platform, examples of such resources are key-value data storages ([KVs](https://developers.cloudflare.com/kv/)) and serverless SQL databases ([D1s](https://developers.cloudflare.com/d1/)).
+
+<read-more>
+
+For more details on Bindings and how to use them please refer to the Cloudflare [Pages](https://developers.cloudflare.com/pages/functions/bindings/) and [Workers](https://developers.cloudflare.com/workers/configuration/bindings/#bindings) documentation.
+</read-more>
+
+> [!TIP]
+> Nitro provides high level API to interact with primitives such as [KV Storage](/docs/storage) and [Database](/docs/database) and you are highly recommended to prefer using them instead of directly depending on low-level APIs for usage stability.
+
+<read-more></read-more>
+
+<read-more></read-more>
+
+In runtime, you can access bindings from the request event via `event.req.runtime.cloudflare.env`. This is for example how you can access a D1 binding:
+
+<warning>
+
+**Nitro v3 Breaking Change:** The `event.context.cloudflare.env` pattern from Nitro v2 no longer works in production. Use `event.req.runtime.cloudflare.env` instead. The old pattern may still appear to work in local dev (via the Wrangler proxy plugin) but will be `undefined` in production deployments.
+</warning>
+
+```ts
+import { defineHandler } from "nitro";
+
+defineHandler(async (event) => {
+  // Nitro v3: access Cloudflare bindings via event.req.runtime.cloudflare.env
+  const { env } = event.req.runtime.cloudflare
+  const stmt = await env.MY_D1.prepare('SELECT id FROM table')
+  const { results } = await stmt.all()
+})
+```
+
+### Access to the bindings in local dev
+
+To access bindings in dev mode, we first define them. You can do this in a `wrangler.jsonc`/`wrangler.json`/`wrangler.toml` file
+
+For example, to define a variable and a KV namespace in `wrangler.toml`:
+
+<code-group>
+
+```ini [wrangler.toml]
+[vars]
+MY_VARIABLE="my-value"
+
+[[kv_namespaces]]
+binding = "MY_KV"
+id = "xxx"
+```
+
+```json [wrangler.json]
+{
+  "vars": {
+    "MY_VARIABLE": "my-value",
+  },
+  "kv_namespaces": [
+    {
+      "binding": "MY_KV",
+      "id": "xxx"
+    }
+  ]
+}
+```
+</code-group>
+
+Next we install the required `wrangler` package (if not already installed):
+
+<pm-install></pm-install>
+
+From this moment, when running
+
+<pm-run></pm-run>
+
+you will be able to access the `MY_VARIABLE` and `MY_KV` from the request event just as illustrated above.
+
+#### Wrangler environments
+
+If you have multiple Wrangler environments, you can specify which Wrangler environment to use during Cloudflare dev emulation:
+
+```ts [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+  preset: 'cloudflare_module',
+  cloudflare: {
+    dev: {
+      environment: 'preview'
+    }
+  }
+})
+```

package/skills/nitro/docs/deploy/providers/deno-deploy.md

@@ -0,0 +1,66 @@
+# Deno Deploy
+
+> Deploy Nitro apps to [Deno Deploy](https://deno.com/deploy).
+
+**Preset:** `deno_deploy`
+
+<read-more></read-more>
+
+## Deploy with the CLI
+
+You can use [deployctl](https://deno.com/deploy/docs/deployctl) to deploy your app.
+
+Login to [Deno Deploy](https://dash.deno.com/account#access-tokens) to obtain a `DENO_DEPLOY_TOKEN` access token, and set it as an environment variable.
+
+```bash
+# Build with the deno_deploy NITRO preset
+NITRO_PRESET=deno_deploy npm run build
+
+# Make sure to run the deployctl command from the output directory
+cd .output
+deployctl deploy --project=my-project server/index.ts
+```
+
+## Deploy within CI/CD using GitHub actions
+
+You just need to include the deployctl GitHub Action as a step in your workflow.
+
+You do not need to set up any secrets for this to work. You do need to link your GitHub repository to your Deno Deploy project and choose the "GitHub Actions" deployment mode. You can do this in your project settings on [Deno Deploy](https://dash.deno.com).
+
+Create the following workflow file in your `.github/workflows` directory:
+
+```yaml [.github/workflows/deno_deploy.yml]
+name: deno-deploy
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    steps:
+      - uses: actions/checkout@v5
+      - run: corepack enable
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 18
+          cache: pnpm
+      - run: pnpm install
+      - run: pnpm build
+        env:
+          NITRO_PRESET: deno_deploy
+      - name: Deploy to Deno Deploy
+        uses: denoland/deployctl@v1
+        with:
+          project: my-project
+          entrypoint: server/index.ts
+          root: .output
+```
+
+## Deno runtime
+
+<read-more></read-more>

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

@@ -0,0 +1,46 @@
+# DigitalOcean
+
+> Deploy Nitro apps to DigitalOcean.
+
+**Preset:** `digital_ocean`
+
+<read-more></read-more>
+
+## Set up application
+
+1. Create a new Digital Ocean app following the [guide](https://docs.digitalocean.com/products/app-platform/how-to/create-apps/).
+
+2. Next, you'll need to configure environment variables. In your app settings, ensure the following app-level environment variables are set:
+
+  ```bash
+  NITRO_PRESET=digital_ocean
+  ```
+
+  [More information](https://docs.digitalocean.com/products/app-platform/how-to/use-environment-variables/).
+
+3. You will need to ensure you set an `engines.node` field in your app's `package.json` to ensure Digital Ocean uses a supported version of Node.js:
+
+  ```json
+  {
+     "engines": {
+        "node": "20.x"
+     }
+  }
+  ```
+
+  [See more information](https://docs.digitalocean.com/products/app-platform/languages-frameworks/nodejs/#node-version).
+
+4. You'll also need to add a run command so Digital Ocean knows what command to run after a build. You can do so by adding a start script to your `package.json`:
+
+  ```json
+  {
+     "scripts": {
+        "start": "node .output/server/index.mjs"
+     }
+  }
+  ```
+
+5. Finally, you'll need to add this start script to your Digital Ocean app's run command. Go to `Components > Settings > Commands`, click "Edit", then add `npm run start`
+
+
+Your app should be live at a Digital Ocean generated URL and you can now follow [the rest of the Digital Ocean deployment guide](https://docs.digitalocean.com/products/app-platform/how-to/manage-deployments/).

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

@@ -0,0 +1,32 @@
+# Firebase
+
+> Deploy Nitro apps to Firebase.
+
+<note>
+
+You will need to be on the [**Blaze plan**](https://firebase.google.com/pricing) (Pay as you go) to get started.
+</note>
+
+## Firebase app hosting
+
+Preset: `firebase_app_hosting`
+
+<read-more></read-more>
+
+<tip>
+
+You can integrate with this provider using [zero configuration](/deploy/#zero-config-providers).
+</tip>
+
+### Project setup
+
+1. Go to the Firebase [console](https://console.firebase.google.com/) and set up a new project.
+2. Select **Build > App Hosting** from the sidebar.  - You may need to upgrade your billing plan at this step.
+
+- Click **Get Started**.  - Choose a region.
+  - Import a GitHub repository (you’ll need to link your GitHub account).
+  - Configure deployment settings (project root directory and branch), and enable automatic rollouts.
+  - Choose a unique ID for your backend.
+
+- Click Finish & Deploy to create your first rollout.
+When you deploy with Firebase App Hosting, the App Hosting preset will be run automatically at build time.

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

@@ -0,0 +1,67 @@
+# Flightcontrol
+
+> Deploy Nitro apps to AWS via Flightcontrol.
+
+**Preset:** `flightcontrol`
+
+<read-more></read-more>
+
+## Set Up your flightcontrol account
+
+On a high level, the steps you will need to follow to deploy a project for the first time are:
+
+1. Create an account at [Flightcontrol](https://app.flightcontrol.dev/signup?ref=nitro)
+2. Create an account at [AWS](https://portal.aws.amazon.com/billing/signup) (if you don't already have one)
+3. Link your AWS account to the Flightcontrol
+4. Authorize the Flightcontrol GitHub App to access your chosen repositories, public or private.
+5. Create a Flightcontrol project with configuration via the Dashboard or with configuration via `flightcontrol.json`.
+
+### Create a project with configuration via the dashboard
+
+1. Create a Flightcontrol project from the Dashboard. Select a repository for the source.
+2. Select the `GUI` config type.
+3. Select the Nuxt preset. This preset will also work for any Nitro-based applications.
+4. Select your preferred AWS server size.
+5. Submit the new project form.
+
+### Create a project with configuration via `flightcontrol.json`
+
+1. Create a Flightcontrol project from your dashboard. Select a repository for the source.
+2. Select the `flightcontrol.json` config type.
+3. Add a new file at the root of your repository called `flightcontrol.json`. Here is an example configuration that creates an AWS fargate service for your app:
+
+```json [flightcontrol.json]
+{
+  "$schema": "https://app.flightcontrol.dev/schema.json",
+  "environments": [
+    {
+      "id": "production",
+      "name": "Production",
+      "region": "us-west-2",
+      "source": {
+        "branch": "main"
+      },
+      "services": [
+        {
+          "id": "nitro",
+          "buildType": "nixpacks",
+          "name": "My Nitro site",
+          "type": "fargate",
+          "domain": "www.yourdomain.com",
+          "outputDirectory": ".output",
+          "startCommand": "node .output/server/index.mjs",
+          "cpu": 0.25,
+          "memory": 0.5
+        }
+      ]
+    }
+  ]
+}
+```
+
+4. Submit the new project form.
+
+<read-more>
+
+Learn more about Flightcontrol's [configuration](https://www.flightcontrol.dev/docs?ref=nitro).
+</read-more>

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

@@ -0,0 +1,67 @@
+# Genezio
+
+> Deploy Nitro apps to Genezio.
+
+**Preset:** `genezio`
+
+<read-more></read-more>
+
+> [!IMPORTANT]
+> 🚧 This preset is currently experimental.
+
+## 1. Project Setup
+
+Create `genezio.yaml` file:
+
+```yaml
+# The name of the project.
+name: nitro-app
+# The version of the Genezio YAML configuration to parse.
+yamlVersion: 2
+backend:
+  # The root directory of the backend.
+  path: .output/
+  # Information about the backend's programming language.
+  language:
+      # The name of the programming language.
+      name: js
+      # The package manager used by the backend.
+      packageManager: npm
+  # Information about the backend's functions.
+  functions:
+      # The name (label) of the function.
+      - name: nitroServer
+      # The path to the function's code.
+        path: server/
+        # The name of the function handler
+        handler: handler
+        # The entry point for the function.
+        entry: index.mjs
+```
+
+<read-more>
+
+To further customize the file to your needs, you can consult the
+[official documentation](https://genezio.com/docs/project-structure/genezio-configuration-file/).
+</read-more>
+
+## 2. Deploy your project
+
+Build with the genezio nitro preset:
+
+```bash
+NITRO_PRESET=genezio npm run build
+```
+
+Deploy with [`genezio`](https://npmjs.com/package/genezio) cli:
+
+<pm-x></pm-x>
+
+<read-more>
+
+To set environment viarables, please check out [Genezio - Environment Variables](https://genezio.com/docs/project-structure/backend-environment-variables).
+</read-more>
+
+## 3. Monitor your project
+
+You can monitor and manage your application through the [Genezio App Dashboard](https://app.genez.io/dashboard). The dashboard URL, also provided after deployment, allows you to access comprehensive views of your project's status and logs.