nitro 3.0.1-alpha.2 → 3.0.260415-beta

package/dist/docs/0.docs/9.database.md

@@ -0,0 +1,185 @@
+> Nitro provides a built-in and lightweight SQL database layer.
+
+The default database connection is **preconfigured** with [SQLite](https://db0.unjs.io/connectors/sqlite) and works out of the box for development mode and any Node.js compatible production deployments. By default, data will be stored in `.data/db.sqlite`.
+
+<read-more></read-more>
+
+> [!IMPORTANT]
+> Database support is currently experimental.
+> Refer to the [db0 issues](https://github.com/unjs/db0/issues) for status and bug report.
+
+In order to enable database layer you need to enable experimental feature flag.
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  experimental: {
+    database: true
+  }
+})
+```
+
+> [!TIP]
+> You can change default connection or define more connections to any of the [supported databases](https://db0.unjs.io/connectors/sqlite).
+
+> [!TIP]
+> You can integrate database instance to any of the [supported ORMs](https://db0.unjs.io/integrations).
+
+## Usage
+
+```ts [server.ts]
+import { defineHandler } from "nitro";
+import { useDatabase } from "nitro/database";
+
+export default defineHandler(async () => {
+  const db = useDatabase();
+
+  // Create users table
+  await db.sql`DROP TABLE IF EXISTS users`;
+  await db.sql`CREATE TABLE IF NOT EXISTS users ("id" TEXT PRIMARY KEY, "firstName" TEXT, "lastName" TEXT, "email" TEXT)`;
+
+  // Add a new user
+  const userId = String(Math.round(Math.random() * 10_000));
+  await db.sql`INSERT INTO users VALUES (${userId}, 'John', 'Doe', '')`;
+
+  // Query for users
+  const { rows } = await db.sql`SELECT * FROM users WHERE id = ${userId}`;
+
+  return {
+    rows,
+  };
+});
+```
+
+### `useDatabase`
+
+Use `useDatabase` to get a database instance. It accepts an optional connection name (defaults to `"default"`).
+
+```ts
+import { useDatabase } from "nitro/database";
+
+// Use the default connection
+const db = useDatabase();
+
+// Use a named connection
+const usersDb = useDatabase("users");
+```
+
+> [!NOTE]
+> When `experimental.database` is enabled, `useDatabase` is auto-imported and available without an explicit import statement.
+
+Database instances are created lazily on first use and cached for subsequent calls with the same connection name. If a connection name is not configured, an error will be thrown.
+
+### `db.sql`
+
+Execute SQL queries using tagged template literals with automatic parameter binding:
+
+```ts
+const db = useDatabase();
+
+// Insert with parameterized values (safe from SQL injection)
+const id = "1001";
+await db.sql`INSERT INTO users VALUES (${id}, 'John', 'Doe', 'john@example.com')`;
+
+// Query with parameters
+const { rows } = await db.sql`SELECT * FROM users WHERE id = ${id}`;
+
+// The result includes rows, changes count, and last insert ID
+const result = await db.sql`INSERT INTO posts (title) VALUES (${"Hello"})`;
+// result.rows, result.changes, result.lastInsertRowid
+```
+
+### `db.exec`
+
+Execute a raw SQL string directly:
+
+```ts
+const db = useDatabase();
+
+await db.exec("CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY, name TEXT)");
+```
+
+### `db.prepare`
+
+Prepare an SQL statement for repeated execution:
+
+```ts
+const db = useDatabase();
+
+const stmt = db.prepare("SELECT * FROM users WHERE id = ?");
+const result = await stmt.bind("1001").all();
+```
+
+## Configuration
+
+You can configure database connections using `database` config:
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  database: {
+    default: {
+      connector: "sqlite",
+      options: { name: "db" }
+    },
+    users: {
+      connector: "postgresql",
+      options: {
+        url: "postgresql://username:password@hostname:port/database_name"
+      },
+    },
+  },
+});
+```
+
+### Development Database
+
+Use the `devDatabase` config to override the database configuration **only for development mode**. This is useful for using a local SQLite database during development while targeting a different database in production.
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  database: {
+    default: {
+      connector: "postgresql",
+      options: {
+        url: "postgresql://username:password@hostname:port/database_name"
+      }
+    }
+  },
+  devDatabase: {
+    default: {
+      connector: "sqlite",
+      options: { name: "dev-db" }
+    }
+  }
+});
+```
+
+> [!TIP]
+> When `experimental.database` is enabled and no `database` or `devDatabase` config is provided, Nitro automatically configures a default SQLite connection. In development mode, data is stored relative to the project root directory. In Node.js production, it uses the default SQLite path.
+
+## Connectors
+
+Nitro supports all [db0 connectors](https://db0.unjs.io/connectors). The `connector` field in the database config accepts any of the following values:
+
+| Connector | Description |
+| --- | --- |
+| `sqlite` | Node.js built-in SQLite (alias for `node-sqlite`) |
+| `node-sqlite` | Node.js built-in SQLite |
+| `better-sqlite3` | [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) |
+| `sqlite3` | [sqlite3](https://github.com/TryGhost/node-sqlite3) |
+| `bun` / `bun-sqlite` | Bun built-in SQLite |
+| `libsql` / `libsql-node` | [libSQL](https://github.com/tursodatabase/libsql) (Node.js) |
+| `libsql-http` | libSQL over HTTP |
+| `libsql-web` | libSQL for web environments |
+| `postgresql` | [PostgreSQL](https://github.com/porsager/postgres) |
+| `mysql2` | [MySQL](https://github.com/sidorares/node-mysql2) |
+| `pglite` | [PGlite](https://github.com/electric-sql/pglite) (embedded PostgreSQL) |
+| `planetscale` | [PlanetScale](https://github.com/planetscale/database-js) serverless |
+| `cloudflare-d1` | [Cloudflare D1](https://developers.cloudflare.com/d1/) |
+| `cloudflare-hyperdrive-mysql` | Cloudflare Hyperdrive with MySQL |
+| `cloudflare-hyperdrive-postgresql` | Cloudflare Hyperdrive with PostgreSQL |

package/dist/docs/1.deploy/0.index/index.md

@@ -0,0 +1,64 @@
+# Deploy
+
+> Learn more about Nitro deploy providers.
+
+Nitro can generate different output formats suitable for different hosting providers from the same code base.
+Using built-in presets, you can easily configure Nitro to adjust its output format with almost no additional code or configuration!
+
+## Default output
+
+The default production output preset is [Node.js server](/deploy/runtimes/node).
+
+When running Nitro in development mode, Nitro will always use a special preset called `nitro-dev` using Node.js with ESM in an isolated Worker environment with behavior as close as possible to the production environment.
+
+## Zero-Config Providers
+
+When deploying to production using CI/CD, Nitro tries to automatically detect the provider environment and set the right one without any additional configuration required. Currently, the providers below can be auto-detected with zero config.
+
+- [aws amplify](/deploy/providers/aws-amplify)
+- [azure](/deploy/providers/azure)
+- [cloudflare](/deploy/providers/cloudflare)
+- [firebase app hosting](/deploy/providers/firebase#firebase-app-hosting)
+- [netlify](/deploy/providers/netlify)
+- [stormkit](/deploy/providers/stormkit)
+- [vercel](/deploy/providers/vercel)
+- [zeabur](/deploy/providers/zeabur)
+
+<warning>
+
+For Turborepo users, zero config detection will be interfered by its Strict Environment Mode. You may need to allow the variables explicitly or use its Loose Environment Mode (with `--env-mode=loose` flag).
+</warning>
+
+Other built-in providers are available with an explicit preset, including [zephyr](/deploy/providers/zephyr).
+
+## Changing the deployment preset
+
+If you need to build Nitro against a specific provider, you can target it by defining an environment variable named `NITRO_PRESET` or `SERVER_PRESET`, or by updating your Nitro [configuration](/docs/configuration) or using `--preset` argument.
+
+Using the environment variable approach is recommended for deployments depending on CI/CD.
+
+**Example:** Defining a `NITRO_PRESET` environment variable
+
+```bash
+nitro build --preset cloudflare_pages
+```
+
+**Example:** Updating the `nitro.config.ts` file
+
+```ts
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  preset: 'cloudflare_pages'
+})
+```
+
+## Compatibility date
+
+Deployment providers regularly update their runtime behavior. Nitro presets are updated to support these new features.
+
+To prevent breaking existing deployments, Nitro uses compatibility dates. These dates let you lock in behavior at the project creation time. You can also opt in to future updates when ready.
+
+When you create a new project, the `compatibilityDate` is set to the current date. This setting is saved in your project's configuration.
+
+You should update the compatibility date periodically. Always test your deployment thoroughly after updating. Below is a list of key dates and their effects.

package/dist/docs/1.deploy/1.runtimes/0.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/dist/docs/1.deploy/1.runtimes/1.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/dist/docs/1.deploy/1.runtimes/2.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/dist/docs/1.deploy/2.providers/0.alwaysdata.md

@@ -0,0 +1,50 @@
+# Alwaysdata
+
+> Deploy Nitro apps to alwaysdata.
+
+**Preset:** `alwaysdata`
+
+<read-more></read-more>
+
+## Set up application
+
+### Pre-requisites
+
+1. [Register a new profile](https://www.alwaysdata.com/en/register/) on alwaysdata platform if you don't have one.
+
+2. Get a free 100Mb plan to host your app.
+
+
+> [!NOTE]
+> Keep in mind your *account name* will be used to provide you a default URL in the form of `account_name.alwaysdata.net`, so choose it wisely. You can also link your existing domains to your account later or register as many accounts under your profile as you need.
+
+### Local deployment
+
+1. Build your project locally with `npm run build -- preset alwaysdata`
+
+2. [Upload your app](https://help.alwaysdata.com/en/remote-access/) to your account in its own directory (e.g. `$HOME/www/my-app`). You can use any protocol you prefer (SSH/FTP/WebDAV…) to do so.
+
+3. On your admin panel, [create a new site](https://admin.alwaysdata.com/site/add/) for your app with the following features:
+  - *Addresses*: `[account_name].alwaysdata.net`
+
+  - *Type*: Node.js
+
+  - *Command*: `node .output/server/index.mjs`
+
+  - *Working directory*: `www/my-app` (adapt it to your deployment path)
+
+  - *Environment*:
+
+    ```ini
+    NITRO_PRESET=alwaysdata
+    ```
+
+  - *Node.js version*: `Default version` is fine; pick no less than `20.0.0` (you can also [set your Node.js version globally](https://help.alwaysdata.com/en/languages/nodejs/configuration/#supported-versions))
+
+  - *Hot restart*: `SIGHUP`
+
+
+  <read-more></read-more>
+
+- Your app is now live at `http(s)://[account_name].alwaysdata.net`.
+

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

@@ -0,0 +1,47 @@
+# AWS Lambda
+
+> Deploy Nitro apps to AWS Lambda.
+
+**Preset:** `aws_lambda`
+
+<read-more></read-more>
+
+Nitro provides a built-in preset to generate output format compatible with [AWS Lambda](https://aws.amazon.com/lambda/).
+The output entrypoint in `.output/server/index.mjs` is compatible with [AWS Lambda format](https://docs.aws.amazon.com/lex/latest/dg/lambda-input-response-format.html).
+
+It can be used programmatically or as part of a deployment.
+
+```ts
+import { handler } from './.output/server'
+
+// Use programmatically
+const { statusCode, headers, body } = handler({ rawPath: '/' })
+```
+
+## Inlining chunks
+
+Nitro output, by default uses dynamic chunks for lazy loading code only when needed. However this sometimes can not be ideal for performance. (See discussions in [nitrojs/nitro#650](https://github.com/nitrojs/nitro/pull/650)). You can enabling chunk inlining behavior using [`inlineDynamicImports`](/config#inlinedynamicimports) config.
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  inlineDynamicImports: true
+});
+```
+
+## Response streaming
+
+<read-more></read-more>
+
+In order to enable response streaming, enable `awsLambda.streaming` flag:
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  awsLambda: {
+    streaming: true
+  }
+});
+```

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

package/dist/docs/1.deploy/2.providers/12.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/dist/docs/1.deploy/2.providers/13.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
+```