@depup/nitro 3.0.260311-beta-depup.0

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

@@ -0,0 +1,15 @@
+# Bun
+
+> Run Nitro apps with Bun runtime.
+
+**Preset:** `bun`
+
+Nitro output is compatible with Bun runtime. While using default [Node.js](/deploy/runtimes/node) you can also run the output in bun, using `bun` preset has advantage of better optimizations.
+
+After building with bun preset using `bun` as preset, you can run server in production using:
+
+```bash
+bun run ./.output/server/index.mjs
+```
+
+<read-more></read-more>

package/skills/nitro/docs/deploy/runtimes/deno.md

@@ -0,0 +1,19 @@
+# Deno
+
+> Run Nitro apps with [Deno](https://deno.com/) runtime.
+
+**Preset:** `deno_server`
+
+You can build your Nitro server using Node.js to run within [Deno Runtime](https://deno.com/runtime) in a custom server.
+
+```bash
+# Build with the deno NITRO preset
+NITRO_PRESET=deno_server npm run build
+
+# Start production server
+deno run --unstable --allow-net --allow-read --allow-env .output/server/index.ts
+```
+
+## Deno Deploy
+
+<read-more></read-more>

package/skills/nitro/docs/deploy/runtimes/node.md

@@ -0,0 +1,63 @@
+# Node.js
+
+> Run Nitro apps with Node.js runtime.
+
+**Preset:** `node_server`
+
+Node.js is the default nitro output preset for production builds and Nitro has native Node.js runtime support.
+
+Build project using nitro CLI:
+
+```bash
+nitro build
+```
+
+When running `nitro build` with the Node server preset, the result will be an entry point that launches a ready-to-run Node server. To try output:
+
+```bash
+$ node .output/server/index.mjs
+Listening on http://localhost:3000
+```
+
+You can now deploy fully standalone `.output` directory to the hosting of your choice.
+
+### Environment Variables
+
+You can customize server behavior using following environment variables:
+
+- `NITRO_PORT` or `PORT` (defaults to `3000`)
+- `NITRO_HOST` or `HOST`
+- `NITRO_UNIX_SOCKET` - if provided (a path to the desired socket file) the service will be served over the provided UNIX socket.
+- `NITRO_SSL_CERT` and `NITRO_SSL_KEY` - if both are present, this will launch the server in HTTPS mode. In the vast majority of cases, this should not be used other than for testing, and the Nitro server should be run behind a reverse proxy like nginx or Cloudflare which terminates SSL.
+- `NITRO_SHUTDOWN_DISABLED` - Disables the graceful shutdown feature when set to `'true'`. If it's set to `'true'`, the graceful shutdown is bypassed to speed up the development process. Defaults to `'false'`.
+- `NITRO_SHUTDOWN_SIGNALS` - Allows you to specify which signals should be handled. Each signal should be separated with a space. Defaults to `'SIGINT SIGTERM'`.
+- `NITRO_SHUTDOWN_TIMEOUT` - Sets the amount of time (in milliseconds) before a forced shutdown occurs. Defaults to `'30000'` milliseconds.
+- `NITRO_SHUTDOWN_FORCE` - When set to true, it triggers `process.exit()` at the end of the shutdown process. If it's set to `'false'`, the process will simply let the event loop clear. Defaults to `'true'`.
+
+## Cluster mode
+**Preset:** `node_cluster`
+
+For more performance and leveraging multi-core handling, you can use cluster preset.
+
+### Environment Variables
+
+In addition to environment variables from the `node_server` preset, you can customize behavior:
+
+- `NITRO_CLUSTER_WORKERS`: Number of cluster workers (default is Number of available cpu cores)
+
+## Handler (advanced)
+**Preset:** `node_middleware`
+
+Nitro also has a more low-level preset that directly exports a middleware usable for custom servers.
+
+When running `nitro build` with the Node middleware preset, the result will be an entry point exporting a middleware handler.
+
+**Example:**
+
+```js
+import { createServer } from 'node:http'
+import { listener } from './.output/server'
+
+const server = createServer(listener)
+server.listen(8080)
+```

package/skills/nitro/docs/docs/assets.md

@@ -0,0 +1,166 @@
+# Assets
+
+Nitro supports two types of assets: **public assets** served directly to clients and **server assets** bundled into the server for programmatic access.
+
+## Public Assets
+
+Nitro handles assets via the `public/` directory.
+
+All assets in `public/` directory will be automatically served. This means that you can access them directly from the browser without any special configuration.
+
+```md
+public/
+  image.png     <-- /image.png
+  video.mp4     <-- /video.mp4
+  robots.txt    <-- /robots.txt
+```
+
+### Caching and Headers
+
+Public assets are served with automatic `ETag` and `Last-Modified` headers for conditional requests. When the client sends `If-None-Match` or `If-Modified-Since` headers, Nitro returns a `304 Not Modified` response.
+
+For assets served from a non-root `baseURL` (such as `/build/`), Nitro prevents fallthrough to application handlers. If a request matches a public asset base but the file is not found, a `404` is returned immediately.
+
+### Production Public Assets
+
+When building your Nitro app, the `public/` directory will be copied to `.output/public/` and a manifest with metadata will be created and embedded in the server bundle.
+
+```json
+{
+  "/image.png": {
+    "type": "image/png",
+    "etag": "\"4a0c-6utWq0Kbk5OqDmksYCa9XV8irnM\"",
+    "mtime": "2023-03-04T21:39:45.086Z",
+    "size": 18956
+  },
+  "/robots.txt": {
+    "type": "text/plain; charset=utf-8",
+    "etag": "\"8-hMqyDrA8fJ0R904zgEPs3L55Jls\"",
+    "mtime": "2023-03-04T21:39:45.086Z",
+    "size": 8
+  },
+  "/video.mp4": {
+    "type": "video/mp4",
+    "etag": "\"9b943-4UwfQXKUjPCesGPr6J5j7GzNYGU\"",
+    "mtime": "2023-03-04T21:39:45.085Z",
+    "size": 637251
+  }
+}
+```
+
+This allows Nitro to know the public assets without scanning the directory, giving high performance with caching headers.
+
+### Custom Public Asset Directories
+
+You can configure additional public asset directories using the `publicAssets` config option. Each entry supports the following properties:
+
+- `dir` -- Path to the directory (resolved relative to `rootDir`).
+- `baseURL` -- URL prefix for serving assets (default: `"/"`).
+- `maxAge` -- Cache `max-age` in seconds. When set, a `Cache-Control: public, max-age=<value>, immutable` header is applied via route rules.
+- `fallthrough` -- Whether requests should fall through to application handlers when the asset is not found. Top-level (`baseURL: "/"`) directories default to `true`; non-root directories default to `false`.
+- `ignore` -- Pass `false` to disable ignore patterns, or an array of glob patterns to override the global `ignore` option.
+
+```js [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+  publicAssets: [
+    {
+      baseURL: "build",
+      dir: "public/build",
+      maxAge: 3600,
+    },
+  ],
+});
+```
+In this example, files in `public/build/` are served under `/build/` with a one-hour cache and no fallthrough to application handlers.
+
+### Compressed Public Assets
+
+Nitro can generate pre-compressed versions of your public assets during the build. When a client sends an `Accept-Encoding` header, the server will serve the compressed version if available. Supported encodings are gzip (`.gz`), brotli (`.br`), and zstd (`.zst`).
+
+Set `compressPublicAssets: true` to enable all encodings:
+
+```js [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+  compressPublicAssets: true,
+});
+```
+
+Or pick specific encodings:
+
+```js [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+  compressPublicAssets: {
+    gzip: true,
+    brotli: true,
+    zstd: false,
+  },
+});
+```
+
+> [!NOTE]
+> Only compressible MIME types (text, JavaScript, JSON, XML, WASM, fonts, SVG, etc.) with a file size of at least 1 KB are compressed. Source map files (`.map`) are excluded.
+
+## Server Assets
+
+All assets in `assets/` directory will be added to the server bundle. After building your application, you can find them in the `.output/server/chunks/raw/` directory. Be careful with the size of your assets, as they will be bundled with the server bundle.
+
+> [!TIP]
+> Unless using `useStorage()`, assets won't be included in the server bundle.
+
+They can be addressed by the `assets:server` mount point using the [storage layer](/docs/storage).
+
+For example, you could store a json file in `assets/data.json` and retrieve it in your handler:
+
+```js
+import { defineHandler } from "nitro";
+
+export default defineHandler(async () => {
+  const data = await useStorage("assets:server").get("data.json");
+
+  return data;
+});
+```
+
+### Custom Server Assets
+
+In order to add assets from a custom directory, you will need to define a path in your nitro config. This allows you to add assets from a directory outside of the `assets/` directory.
+
+Each entry in `serverAssets` supports the following properties:
+
+- `baseName` -- Name used as the storage mount point (accessed via `assets:<baseName>`).
+- `dir` -- Path to the directory (resolved relative to `rootDir`).
+- `pattern` -- Glob pattern for file inclusion (default: `"**/*"`).
+- `ignore` -- Array of glob patterns to exclude files.
+
+```js [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+  serverAssets: [
+    {
+      baseName: "templates",
+      dir: "./templates",
+    },
+  ],
+});
+```
+Then you can use the `assets:templates` base to retrieve your assets.
+
+```ts [handlers/success.ts]
+import { defineHandler } from "nitro";
+
+export default defineHandler(async (event) => {
+  const html = await useStorage("assets:templates").get("success.html");
+
+  return html;
+});
+```
+
+> [!TIP]
+> During development, server assets are read directly from the filesystem using the `fs` unstorage driver. In production, they are bundled into the server as lazy imports with pre-computed metadata (MIME type, ETag, modification time).