@depup/nitro 3.0.260311-beta-depup.0

package/skills/nitro/docs/docs/cache.md

@@ -0,0 +1,408 @@
+# Cache
+
+> Nitro provides a caching system built on top of the storage layer, powered by [ocache](https://github.com/unjs/ocache).
+
+## Cached handlers
+
+To cache an event handler, you simply need to use the `defineCachedHandler` method.
+
+It works like `defineHandler` but with an second parameter for the [cache options](#options).
+
+```ts [routes/cached.ts]
+import { defineCachedHandler } from "nitro/cache";
+
+export default defineCachedHandler((event) => {
+  return "I am cached for an hour";
+}, { maxAge: 60 * 60 });
+```
+
+With this example, the response will be cached for 1 hour and a stale value will be sent to the client while the cache is being updated in the background. If you want to immediately return the updated response set `swr: false`.
+
+See the [options](#options) section for more details about the available options.
+
+<important>
+
+**Request headers are dropped** when handling cached responses. Use the [`varies` option](#options) to consider specific headers when caching and serving the responses.
+</important>
+
+### Automatic HTTP headers
+
+When using `defineCachedHandler`, Nitro automatically manages HTTP cache headers on cached responses:
+
+- **`etag`** -- A weak ETag (`W/"..."`) is generated from the response body hash if not already set by the handler.
+- **`last-modified`** -- Set to the current time when the response is first cached, if not already set.
+- **`cache-control`** -- Automatically set based on the `swr`, `maxAge`, and `staleMaxAge` options:  - With `swr: true`: `s-maxage=<maxAge>, stale-while-revalidate=<staleMaxAge>`
+  - With `swr: false`: `max-age=<maxAge>`
+
+
+### Conditional requests (304 Not Modified)
+Cached handlers automatically support conditional requests. When a client sends `if-none-match` or `if-modified-since` headers matching the cached response, Nitro returns a `304 Not Modified` response without a body.
+
+### Request method filtering
+
+Only `GET` and `HEAD` requests are cached. All other HTTP methods (`POST`, `PUT`, `DELETE`, etc.) automatically bypass the cache and call the handler directly.
+
+### Request deduplication
+
+When multiple concurrent requests hit the same cache key while the cache is being resolved, only one invocation of the handler runs. All concurrent requests wait for and share the same result.
+
+## Cached functions
+
+You can also cache a function using the `defineCachedFunction` function. This is useful for caching the result of a function that is not an event handler, but is part of one, and reusing it in multiple handlers.
+
+For example, you might want to cache the result of an API call for one hour:
+
+```ts [routes/api/stars/[...repo\].ts]
+import { defineCachedFunction } from "nitro/cache";
+import { defineHandler, type H3Event } from "nitro";
+
+export default defineHandler(async (event) => {
+  const { repo } = event.context.params;
+  const stars = await cachedGHStars(repo).catch(() => 0)
+
+  return { repo, stars }
+});
+
+const cachedGHStars = defineCachedFunction(async (repo: string) => {
+  const data = await fetch(`https://api.github.com/repos/${repo}`).then(res => res.json());
+
+  return data.stargazers_count;
+}, {
+  maxAge: 60 * 60,
+  name: "ghStars",
+  getKey: (repo: string) => repo
+});
+```
+
+The stars will be cached in development inside `.nitro/cache/functions/ghStars/<owner>/<repo>.json` with `value` being the number of stars.
+
+```json
+{"expires":1677851092249,"value":43991,"mtime":1677847492540,"integrity":"ZUHcsxCWEH"}
+```
+
+<important>
+
+Because the cached data is serialized to JSON, it is important that the cached function does not return anything that cannot be serialized, such as Symbols, Maps, Sets...
+</important>
+
+<callout>
+
+If you are using edge workers to host your application, you should follow the instructions below.
+:<collapsible></collapsible>
+In edge workers, the instance is destroyed after each request. Nitro automatically uses `event.waitUntil` to keep the instance alive while the cache is being updated while the response is sent to the client.
+
+To ensure that your cached functions work as expected in edge workers, **you should always pass the `event` as the first argument to the function using `defineCachedFunction`.**
+
+```ts [routes/api/stars/[...repo\].ts] {5,10,17}
+import { defineCachedFunction } from "nitro/cache";
+
+
+export default defineHandler(async (event) => {
+  const { repo } = event.context.params;
+  const stars = await cachedGHStars(event, repo).catch(() => 0)
+
+  return { repo, stars }
+});
+
+const cachedGHStars = defineCachedFunction(async (event: H3Event, repo: string) => {
+  const data = await fetch(`https://api.github.com/repos/${repo}`).then(res => res.json());
+
+  return data.stargazers_count;
+}, {
+  maxAge: 60 * 60,
+  name: "ghStars",
+  getKey: (event: H3Event, repo: string) => repo
+});
+```
+
+This way, the function will be able to keep the instance alive while the cache is being updated without slowing down the response to the client.
+</callout>
+
+::
+
+## Using route rules
+
+This feature enables you to add caching routes based on a glob pattern directly in the main configuration file. This is especially useful to have a global cache strategy for a part of your application.
+
+Cache all the blog routes for 1 hour with `stale-while-revalidate` behavior:
+
+```ts [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+  routeRules: {
+    "/blog/**": { cache: { maxAge: 60 * 60 } },
+  },
+});
+```
+
+If we want to use a [custom cache storage](#cache-storage) mount point, we can use the `base` option.
+
+```ts [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+  storage: {
+    redis: {
+      driver: "redis",
+      url: "redis://localhost:6379",
+    },
+  },
+  routeRules: {
+    "/blog/**": { cache: { maxAge: 60 * 60, base: "redis" } },
+  },
+});
+```
+
+### Route rules shortcuts
+
+You can use the `swr` shortcut for enabling `stale-while-revalidate` caching on route rules. When set to `true`, SWR is enabled with the default `maxAge`. When set to a number, it is used as the `maxAge` value in seconds.
+
+```ts [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+  routeRules: {
+    "/blog/**": { swr: true },
+    "/api/**": { swr: 3600 },
+  },
+});
+```
+
+To explicitly disable caching on a route, set `cache: false`:
+
+```ts [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+  routeRules: {
+    "/api/realtime/**": { cache: false },
+  },
+});
+```
+
+<note>
+
+When using route rules, cached handlers use the group `'nitro/route-rules'` instead of the default `'nitro/handlers'`.
+</note>
+
+## Cache storage
+
+Nitro stores the data in the `cache` storage mount point.
+
+- In production, it will use the [memory driver](https://unstorage.unjs.io/drivers/memory) by default.
+- In development, it will use the [filesystem driver](https://unstorage.unjs.io/drivers/fs), writing to a temporary dir (`.nitro/cache`).
+To overwrite the production storage, set the `cache` mount point using the `storage` option:
+
+```ts [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+  storage: {
+    cache: {
+      driver: 'redis',
+      /* redis connector options */
+    }
+  }
+})
+```
+
+In development, you can also overwrite the cache mount point using the `devStorage` option:
+
+```ts [nitro.config.ts]
+import { defineNitroConfig } from "nitro/config";
+
+export default defineNitroConfig({
+  storage: {
+    cache: {
+      // production cache storage
+    },
+  },
+  devStorage: {
+    cache: {
+      // development cache storage
+    }
+  }
+})
+```
+
+## Options
+
+The `defineCachedHandler` and `defineCachedFunction` functions accept the following options:
+
+### Shared options
+
+These options are available for both `defineCachedHandler` and `defineCachedFunction`:
+
+<field-group>
+
+<field>
+
+Name of the storage mountpoint to use for caching. :br
+Default to `cache`.
+</field>
+
+<field>
+
+Guessed from function name if not provided, and falls back to `'_'` otherwise.
+</field>
+
+<field>
+
+Defaults to `'nitro/handlers'` for handlers and `'nitro/functions'` for functions.
+</field>
+
+<field>
+
+A function that accepts the same arguments as the original function and returns a cache key (`String`). :br
+If not provided, a built-in hash function will be used to generate a key based on the function arguments. For cached handlers, the key is derived from the request URL path and search params.
+</field>
+
+<field>
+
+A value that invalidates the cache when changed. :br
+By default, it is computed from **function code**, used in development to invalidate the cache when the function code changes.
+</field>
+
+<field>
+
+Maximum age that cache is valid, in seconds. :br
+Default to `1` (second).
+</field>
+
+<field>
+
+Maximum age that a stale cache is valid, in seconds. If set to `-1` a stale value will still be sent to the client while the cache updates in the background. :br
+Defaults to `0` (disabled).
+</field>
+
+<field>
+
+Enable `stale-while-revalidate` behavior to serve a stale cached response while asynchronously revalidating it. :br
+When enabled, stale cached values are returned immediately while revalidation happens in the background. When disabled, the caller waits for the fresh value before responding (the stale entry is cleared). :br
+Defaults to `true`.
+</field>
+
+<field>
+
+A function that returns a `boolean` to invalidate the current cache and create a new one.
+</field>
+
+<field>
+
+A function that returns a `boolean` to bypass the current cache without invalidating the existing entry.
+</field>
+
+<field>
+
+A custom error handler called when the cached function throws. :br
+By default, errors are logged to the console and captured by the Nitro error handler.
+</field>
+</field-group>
+
+### Handler-only options
+
+These options are only available for `defineCachedHandler`:
+
+<field-group>
+
+<field>
+
+When `true`, skip full response caching and only handle conditional request headers (`if-none-match`, `if-modified-since`) for `304 Not Modified` responses. The handler is called on every request but benefits from conditional caching.
+</field>
+
+<field>
+
+An array of request header names to vary the cache key on. Headers listed here are preserved on the request during cache resolution and included in the cache key, making the cache unique per combination of header values. :br :br
+Headers **not** listed in `varies` are stripped from the request before calling the handler to ensure consistent cache hits. :br :br
+For multi-tenant environments, you may want to pass `['host', 'x-forwarded-host']` to ensure these headers are not discarded and that the cache is unique per tenant.
+</field>
+</field-group>
+
+### Function-only options
+
+These options are only available for `defineCachedFunction`:
+
+<field-group>
+
+<field>
+
+Transform the cache entry before returning. The return value replaces the cached value.
+</field>
+
+<field>
+
+Validate a cache entry. Return `false` to treat the entry as invalid and trigger re-resolution.
+</field>
+</field-group>
+
+## SWR behavior
+
+The `stale-while-revalidate` (SWR) pattern is enabled by default (`swr: true`). Understanding how it interacts with other options:
+
+| `swr` | `maxAge` | Behavior |
+| --- | --- | --- |
+| `true` (default) | `1` (default) | Cache for 1 second, serve stale while revalidating |
+| `true` | `3600` | Cache for 1 hour, serve stale while revalidating |
+| `false` | `3600` | Cache for 1 hour, wait for fresh value when expired |
+| `true` | `3600` with `staleMaxAge: 600` | Cache for 1 hour, serve stale for up to 10 minutes while revalidating |
+
+When `swr` is enabled and a cached value exists but has expired:
+
+1. The stale cached value is returned immediately to the client.
+2. The function/handler is called in the background to refresh the cache.
+3. On edge workers, `event.waitUntil` is used to keep the background refresh alive.
+When `swr` is disabled and a cached value has expired:
+
+1. The stale entry is cleared.
+2. The client waits for the function/handler to resolve with a fresh value.
+
+## Cache keys and invalidation
+When using the `defineCachedFunction` or `defineCachedHandler` functions, the cache key is generated using the following pattern:
+
+```ts
+`${options.base}:${options.group}:${options.name}:${options.getKey(...args)}.json`
+```
+
+For example, the following function:
+
+```ts
+import { defineCachedFunction } from "nitro/cache";
+
+const getAccessToken = defineCachedFunction(() => {
+  return String(Date.now())
+}, {
+  maxAge: 10,
+  name: "getAccessToken",
+  getKey: () => "default"
+});
+```
+
+Will generate the following cache key:
+
+```ts
+cache:nitro/functions:getAccessToken:default.json
+```
+
+You can invalidate the cached function entry with:
+
+```ts
+import { useStorage } from "nitro/storage";
+
+await useStorage('cache').removeItem('nitro/functions:getAccessToken:default.json')
+```
+
+<note>
+
+For cached handlers, the cache key includes a hash of the URL path and, when using the [`varies`](#handler-only-options) option, hashes of the specified header values appended to the key.
+</note>
+
+<note>
+
+Responses with HTTP status codes `>= 400` or with an undefined body are not cached. This prevents caching error responses.
+</note>
+
+<read-more>
+
+Read more about the Nitro storage.
+</read-more>

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