nitro 3.0.1-alpha.2 → 3.0.260415-beta

package/dist/docs/0.docs/6.storage.md

@@ -0,0 +1,261 @@
+# KV Storage
+
+> Nitro provides a built-in storage layer that can abstract filesystem or database or any other data source.
+
+Nitro has built-in integration with [unstorage](https://unstorage.unjs.io) to provide a runtime agnostic persistent layer.
+
+## Usage
+
+To use the storage layer, you can use the `useStorage()` utility to access the storage instance.
+
+```ts
+import { useStorage } from "nitro/storage";
+
+// Default storage (in-memory)
+await useStorage().setItem("test:foo", { hello: "world" });
+const value = await useStorage().getItem("test:foo");
+
+// You can specify a base prefix with useStorage(base)
+const testStorage = useStorage("test");
+await testStorage.setItem("foo", { hello: "world" });
+await testStorage.getItem("foo"); // { hello: "world" }
+
+// You can use generics to type the return value
+await useStorage<{ hello: string }>("test").getItem("foo");
+await useStorage("test").getItem<{ hello: string }>("foo");
+```
+
+<read-more></read-more>
+
+### Available methods
+
+The storage instance returned by `useStorage()` provides the following methods:
+
+| Method | Description |
+| --- | --- |
+| `getItem(key)` | Get the value of a key. Returns `null` if the key does not exist. |
+| `getItems(items)` | Get multiple items at once. Accepts an array of keys or `{ key, options }` objects. |
+| `getItemRaw(key)` | Get the raw value of a key without parsing. Useful for binary data. |
+| `setItem(key, value)` | Set the value of a key. |
+| `setItems(items)` | Set multiple items at once. Accepts an array of `{ key, value }` objects. |
+| `setItemRaw(key, value)` | Set the raw value of a key without serialization. |
+| `hasItem(key)` | Check if a key exists. Returns a boolean. |
+| `removeItem(key)` | Remove a key from storage. |
+| `getKeys(base?)` | Get all keys, optionally filtered by a base prefix. |
+| `clear(base?)` | Clear all keys, optionally filtered by a base prefix. |
+| `getMeta(key)` | Get metadata for a key (e.g., `mtime`, `atime`, `ttl`). |
+| `setMeta(key, meta)` | Set metadata for a key. |
+| `removeMeta(key)` | Remove metadata for a key. |
+| `mount(base, driver)` | Dynamically mount a storage driver at a base path. |
+| `unmount(base)` | Unmount a storage driver from a base path. |
+| `watch(callback)` | Watch for changes. Callback receives `(event, key)` where event is `"update"` or `"remove"`. |
+| `unwatch()` | Stop watching for changes. |
+
+Shorthand aliases are also available: `get`, `set`, `has`, `del`, `remove`, `keys`.
+
+```ts
+import { useStorage } from "nitro/storage";
+
+// Get all keys under a prefix
+const keys = await useStorage("test").getKeys();
+
+// Check if a key exists
+const exists = await useStorage().hasItem("test:foo");
+
+// Remove a key
+await useStorage().removeItem("test:foo");
+
+// Get raw binary data
+const raw = await useStorage().getItemRaw("assets/server:image.png");
+
+// Get metadata (type, etag, mtime, etc.)
+const meta = await useStorage("assets/server").getMeta("file.txt");
+```
+
+## Configuration
+
+You can mount one or multiple custom storage drivers using the `storage` option.
+
+The key is the mount point name, and the value is the driver name and configuration.
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  storage: {
+    redis: {
+      driver: "redis",
+      /* redis connector options */
+    }
+  }
+})
+```
+
+Then, you can use the redis storage using the `useStorage("redis")` function.
+
+<read-more>
+
+You can find the driver list on [unstorage documentation](https://unstorage.unjs.io/) with their configuration.
+</read-more>
+
+### Development storage
+
+You can use the `devStorage` option to override storage configuration during development and prerendering.
+
+This is useful when your production driver is not available in development (e.g., a managed Redis instance).
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  storage: {
+    db: {
+      driver: "redis",
+      host: "prod.example.com",
+    }
+  },
+  devStorage: {
+    db: {
+      driver: "fs",
+      base: "./.data/db"
+    }
+  }
+})
+```
+
+When running in development mode, `devStorage` mounts are merged on top of `storage` mounts, allowing you to use a local filesystem driver or an in-memory driver while developing.
+
+## Built-in mount points
+
+Nitro automatically mounts the following storage paths:
+
+### `/assets`
+
+Server assets are mounted at the `/assets` base path. This mount point provides read-only access to bundled server assets (see [Server assets](#server-assets)).
+
+```ts
+import { useStorage } from "nitro/storage";
+
+// Access server assets via the /assets mount
+const content = await useStorage("assets/server").getItem("my-file.txt");
+```
+
+### Default (in-memory)
+
+The root storage (without a base path) uses an in-memory driver by default. Data stored here is not persisted across restarts.
+
+```ts
+import { useStorage } from "nitro/storage";
+
+// In-memory by default, not persisted
+await useStorage().setItem("counter", 1);
+```
+
+To persist data, mount a driver with a persistent backend (e.g., `fs`, `redis`, etc.) using the `storage` configuration option.
+
+## Server assets
+
+Nitro allows you to bundle files from an `assets/` directory at the root of your project. These files are accessible at runtime via the `assets/server` storage mount.
+
+```
+my-project/
+  assets/
+    data.json
+    templates/
+      welcome.html
+  server/
+    routes/
+      index.ts
+```
+
+```ts [server/routes/index.ts]
+import { useStorage } from "nitro/storage";
+
+export default defineHandler(async () => {
+  const serverAssets = useStorage("assets/server");
+
+  const keys = await serverAssets.getKeys();
+  const data = await serverAssets.getItem("data.json");
+  const template = await serverAssets.getItem("templates/welcome.html");
+
+  return { keys, data, template };
+});
+```
+
+### Custom asset directories
+
+You can register additional asset directories using the `serverAssets` config option:
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  serverAssets: [
+    {
+      baseName: "templates",
+      dir: "./templates",
+    }
+  ]
+})
+```
+
+Custom asset directories are accessible under `assets/<baseName>`:
+
+```ts
+import { useStorage } from "nitro/storage";
+
+const templates = useStorage("assets/templates");
+const keys = await templates.getKeys();
+const html = await templates.getItem("email.html");
+```
+
+### Asset metadata
+
+Server assets include metadata such as content type, ETag, and modification time:
+
+```ts
+import { useStorage } from "nitro/storage";
+
+const serverAssets = useStorage("assets/server");
+
+const meta = await serverAssets.getMeta("image.png");
+// { type: "image/png", etag: "\"...\"", mtime: "2024-01-01T00:00:00.000Z" }
+
+// Useful for setting response headers
+const raw = await serverAssets.getItemRaw("image.png");
+```
+
+<note>
+
+In development, server assets are read directly from the filesystem. In production, they are bundled and inlined into the build output.
+</note>
+
+## Runtime configuration
+
+In scenarios where the mount point configuration is not known until runtime, Nitro can dynamically add mount points during startup using [plugins](/docs/plugins).
+
+```ts [plugins/storage.ts]
+import { useStorage } from "nitro/storage";
+import { definePlugin } from "nitro";
+import redisDriver from "unstorage/drivers/redis";
+
+export default definePlugin(() => {
+  const storage = useStorage()
+
+  // Dynamically pass in credentials from runtime configuration, or other sources
+  const driver = redisDriver({
+    base: "redis",
+    host: process.env.REDIS_HOST,
+    port: process.env.REDIS_PORT,
+    /* other redis connector options */
+  })
+
+  // Mount driver
+  storage.mount("redis", driver)
+})
+```
+
+<warning>
+
+This is a temporary workaround, with a better solution coming in the future! Keep a lookout on the GitHub issue [here](https://github.com/nitrojs/nitro/issues/1161#issuecomment-1511444675).
+</warning>

package/dist/docs/0.docs/7.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 { defineConfig } from "nitro";
+
+export default defineConfig({
+  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 { defineConfig } from "nitro";
+
+export default defineConfig({
+  compressPublicAssets: true,
+});
+```
+
+Or pick specific encodings:
+
+```js [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  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 { defineConfig } from "nitro";
+
+export default defineConfig({
+  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).

package/dist/docs/0.docs/8.configuration.md

@@ -0,0 +1,256 @@
+# Configuration
+
+> Customize and extend Nitro defaults.
+
+<read-more>
+
+See [config reference](/config) for available options.
+</read-more>
+
+## Config file
+
+You can customize your Nitro builder with a configuration file.
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  // Nitro options
+})
+```
+
+```ts [vite.config.ts]
+import { defineConfig } from 'vite'
+import { nitro } from 'nitro/vite'
+
+export default defineConfig({
+  plugins: [
+    nitro()
+  ],
+  nitro: {
+    // Nitro options
+  }
+})
+
+```
+
+> [!TIP]
+> Nitro loads the configuration using [c12](https://github.com/unjs/c12), giving more  possibilities such as using `.nitrorc` file in current working directory or in the user's home directory.
+
+### Environment-specific config
+
+Using [c12](https://github.com/unjs/c12) conventions, you can provide environment-specific overrides using `$development` and `$production` keys:
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  logLevel: 3,
+  $development: {
+    // Options applied only in development mode
+    debug: true,
+  },
+  $production: {
+    // Options applied only in production builds
+    minify: true,
+  },
+})
+```
+
+The environment name is `"development"` during `nitro dev` and `"production"` during `nitro build`.
+
+### Extending configs
+
+You can extend from other configs or presets using the `extends` key:
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  extends: "./base.config",
+})
+```
+
+### Config from `package.json`
+
+You can also provide Nitro configuration under the `nitro` key in your `package.json` file.
+
+## Directory options
+
+Nitro provides several options for controlling directory structure:
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `rootDir` | `.` (current directory) | The root directory of the project. |
+| `serverDir` | `false` | Server source directory (set to `"server"` or `"./"` to enable). |
+| `buildDir` | `node_modules/.nitro` | Directory for build artifacts. |
+| `output.dir` | `.output` | Production output directory. |
+| `output.serverDir` | `.output/server` | Server output directory. |
+| `output.publicDir` | `.output/public` | Public assets output directory. |
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  serverDir: "server",
+  buildDir: "node_modules/.nitro",
+  output: {
+    dir: ".output",
+  },
+})
+```
+
+> [!NOTE]
+> The `srcDir` option is deprecated. Use `serverDir` instead.
+
+## Environment variables
+
+Certain Nitro behaviors can be configured using environment variables:
+
+| Variable | Description |
+| --- | --- |
+| `NITRO_PRESET` | Override the deployment preset. |
+| `NITRO_COMPATIBILITY_DATE` | Set the compatibility date. |
+| `NITRO_APP_BASE_URL` | Override the base URL (default: `/`). |
+
+## Runtime configuration
+
+Nitro provides a runtime config API to expose configuration within your application, with the ability to update it at runtime by setting environment variables. This is useful when you want to expose different configuration values for different environments (e.g. development, staging, production). For example, you can use this to expose different API endpoints for different environments or to expose different feature flags.
+
+First, you need to define the runtime config in your configuration file.
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  runtimeConfig: {
+    apiToken: "dev_token", // `dev_token` is the default value
+  }
+});
+```
+
+You can now access the runtime config using `useRuntimeConfig()`.
+
+```ts [api/example.get.ts]
+import { defineHandler } from "nitro";
+import { useRuntimeConfig } from "nitro/runtime-config";
+
+export default defineHandler((event) => {
+  return useRuntimeConfig().apiToken; // Returns `dev_token`
+});
+```
+
+### Nested objects
+
+Runtime config supports nested objects. Keys at any depth are mapped to environment variables using the `NITRO_` prefix and `UPPER_SNAKE_CASE` conversion:
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  runtimeConfig: {
+    database: {
+      host: "localhost",
+      port: 5432,
+    },
+  },
+});
+```
+
+```bash [.env]
+NITRO_DATABASE_HOST="db.example.com"
+NITRO_DATABASE_PORT="5433"
+```
+
+> [!NOTE]
+> Only keys defined in `runtimeConfig` in your config file will be considered. You cannot introduce new keys using environment variables alone.
+
+### Serialization
+
+Runtime config values must be serializable (strings, numbers, booleans, plain objects, and arrays). Non-serializable values (class instances, functions, etc.) will trigger a warning at build time.
+
+Values that are `undefined` or `null` in the config are replaced with empty strings (`""`) as a fallback.
+
+### Local development
+
+You can update the runtime config using environment variables. You can use a `.env` or `.env.local` file in development and use platform variables in production (see below).
+
+Create an `.env` file in your project root:
+
+```bash [.env]
+NITRO_API_TOKEN="123"
+```
+
+Re-start the development server, fetch the `/api/example` endpoint and you should see `123` as the response instead of `dev_token`.
+
+> [!NOTE]
+> The `.env` and `.env.local` files are only loaded during development (`nitro dev`). In production, use your platform's native environment variable mechanism.
+
+Do not forget that you can still universally access environment variables using `import.meta.env` or `process.env` but avoid using them in ambient global contexts to prevent unexpected behavior.
+
+### Production
+
+You can define variables in your production environment to update the runtime config.
+
+<warning>
+
+All variables must be prefixed with `NITRO_` to be applied to the runtime config. They will override the runtime config variables defined within your `nitro.config.ts` file.
+</warning>
+
+```bash [.env]
+NITRO_API_TOKEN="123"
+```
+
+In runtime config, define key using camelCase. In environment variables, define key using snake_case and uppercase.
+
+```ts
+{
+  helloWorld: "foo"
+}
+```
+
+```bash
+NITRO_HELLO_WORLD="foo"
+```
+
+### Custom env prefix
+
+You can configure a secondary environment variable prefix using the `nitro.envPrefix` runtime config key. This prefix is checked in addition to the default `NITRO_` prefix:
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  runtimeConfig: {
+    nitro: {
+      envPrefix: "APP_",
+    },
+    apiToken: "",
+  },
+});
+```
+
+With this configuration, both `NITRO_API_TOKEN` and `APP_API_TOKEN` will be checked as overrides.
+
+### Env expansion
+
+When enabled, environment variable references using `{{VAR_NAME}}` syntax in runtime config string values are expanded at runtime:
+
+```ts [nitro.config.ts]
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  experimental: {
+    envExpansion: true,
+  },
+  runtimeConfig: {
+    url: "https://{{APP_DOMAIN}}/api",
+  },
+});
+```
+
+```bash
+APP_DOMAIN="example.com"
+```
+
+At runtime, `useRuntimeConfig().url` will resolve to `"https://example.com/api"`.