@netlify/agent-runner-cli 1.69.2 → 1.70.0

package/dist/skills/netlify-blobs/SKILL.md

@@ -0,0 +1,396 @@
+---
+name: netlify-blobs
+description: Store and retrieve data using Netlify Blobs key-value storage. Use when implementing file storage, JSON persistence, caching, or any data that needs to persist between requests without an external database.
+---
+
+# Netlify Blobs
+
+Netlify Blobs is a zero-configuration key-value store optimized for frequent reads and infrequent writes. It provides
+persistent storage scoped to your site with automatic provisioning and access control. The API will be the same across
+all compute types (serverless functions, edge functions, build plugins, etc.).
+
+Requires Fetch API support (Node.js 18+ recommended).
+
+Prefer using Netlify Blobs over creating a new database unless the user needs relational structures, complex search, or
+explicitly asks for a different tool.
+
+## Quick Start
+
+Install the package and use `getStore` to start storing data:
+
+```bash
+npm install @netlify/blobs
+```
+
+```typescript
+import { getStore } from '@netlify/blobs'
+
+const store = getStore('my-store')
+
+// Write
+await store.set('greeting', 'Hello, world!')
+await store.setJSON('config', { theme: 'dark', lang: 'en' })
+
+// Read
+const greeting = await store.get('greeting', { type: 'text' })
+const config = await store.get('config', { type: 'json' })
+
+// Delete
+await store.delete('greeting')
+```
+
+## API Reference
+
+### Global Functions
+
+#### `getStore(name: string | StoreOptions): Store`
+
+Returns a store instance for a site-level namespace. Data persists across deploys.
+
+```typescript
+import { getStore } from '@netlify/blobs'
+
+// Simple usage
+const store = getStore('my-store')
+
+// With options
+const store = getStore({
+  name: 'my-store',
+  consistency: 'strong',
+})
+```
+
+**`StoreOptions`:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `string` | Store namespace (required) |
+| `consistency` | `'strong' \| 'eventual'` | Consistency model (default: `'eventual'`) |
+
+ONLY add the options argument if the user needs strong consistency.
+
+#### `getDeployStore(options?: DeployStoreOptions): Store`
+
+Returns a store scoped to a specific deploy. Data is isolated per deploy and immutable after deploy finishes.
+
+```typescript
+import { getDeployStore } from '@netlify/blobs'
+
+const store = getDeployStore()
+```
+
+Use deploy stores for data that should be tied to a specific deploy snapshot (e.g., pre-rendered page data, build
+artifacts). ONLY add the options argument if the user needs strong consistency.
+
+#### `listStores(options?: ListStoresOptions): Promise<{ stores: string[] }>`
+
+Lists all site-level store names. Supports pagination for sites with many stores.
+
+```typescript
+import { listStores } from '@netlify/blobs'
+
+const { stores } = await listStores()
+console.log(stores) // ['my-store', 'uploads', ...]
+
+// Paginated iteration
+for await (const page of listStores({ paginate: true })) {
+  console.log(page.stores)
+}
+```
+
+DO NOT pass options unless paginating.
+
+### Store Methods
+
+THESE ARE THE ONLY STORE METHODS. DO NOT MAKE UP NEW ONES.
+
+#### `set(key: string, value: string | ArrayBuffer | Blob, options?: SetOptions): Promise<void>`
+
+Stores a value. Supports strings, binary data (ArrayBuffer), and Blob objects.
+
+```typescript
+await store.set('my-key', 'my-value')
+await store.set('binary-key', new Uint8Array([1, 2, 3]))
+await store.set('with-meta', 'value', {
+  metadata: { contentType: 'text/plain', author: 'system' },
+})
+```
+
+**`SetOptions`:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `metadata` | `Record<string, string>` | Custom metadata (max 64 KB total) |
+
+NEVER add metadata unless the user explicitly instructs you to.
+
+#### `setJSON(key: string, value: any, options?: SetOptions): Promise<void>`
+
+Stores a JSON-serializable value. Automatically serializes with `JSON.stringify`.
+
+```typescript
+await store.setJSON('config', { theme: 'dark', lang: 'en' })
+await store.setJSON('users/123', { name: 'Alice', role: 'admin' })
+```
+
+NEVER add metadata unless the user explicitly instructs you to.
+
+#### `get(key: string, options?: GetOptions): Promise<string | Blob | object | ArrayBuffer | null>`
+
+Retrieves a value by key. Returns `null` if the key does not exist.
+
+```typescript
+// As text (default)
+const text = await store.get('my-key', { type: 'text' })
+
+// As JSON
+const data = await store.get('config', { type: 'json' })
+
+// As ArrayBuffer
+const binary = await store.get('binary-key', { type: 'arrayBuffer' })
+
+// As Blob
+const blob = await store.get('image', { type: 'blob' })
+
+// As ReadableStream
+const stream = await store.get('large-file', { type: 'stream' })
+```
+
+**`GetOptions.type`:** `'text'` | `'json'` | `'arrayBuffer'` | `'blob'` | `'stream'`
+
+ALWAYS use `store.get('key', { type: 'json' })` instead of `JSON.parse(await store.get('key'))`. NEVER add the options
+argument unless you need a specific type.
+
+#### `getWithMetadata(key: string, options?: GetOptions): Promise<{ data, metadata } | null>`
+
+Retrieves a value along with its custom metadata.
+
+```typescript
+const result = await store.getWithMetadata('my-key', { type: 'text' })
+if (result) {
+  console.log(result.data)     // the value
+  console.log(result.metadata) // { contentType: '...', ... }
+}
+```
+
+NEVER add the second getOpts arg unless you need an explicit type or have an etag to check against. AVOID adding it
+unless it's reliably available but IF an etag is provided, it will only return the blob if the etag is different than
+what's stored.
+
+#### `getMetadata(key: string): Promise<{ metadata: Record<string, string> } | null>`
+
+Retrieves only the metadata for a key, without downloading the value. Useful for checking existence or reading metadata
+on large blobs.
+
+```typescript
+const result = await store.getMetadata('my-key')
+if (result) {
+  console.log(result.metadata)
+}
+```
+
+NEVER add the second getOpts arg unless you need an explicit type or have an etag to check against. AVOID adding it
+unless it's reliably available but IF an etag is provided, it will only return the blob if the etag is different than
+what's stored.
+
+#### `list(options?: ListOptions): Promise<{ blobs: ListEntry[], directories: string[] }>`
+
+Lists entries in the store. By default retrieves all pages. Use `paginate: true` for an `AsyncIterable`.
+
+```typescript
+// List all
+const { blobs } = await store.list()
+
+// With prefix filter
+const { blobs } = await store.list({ prefix: 'users/' })
+
+// With hierarchical browsing
+const { blobs, directories } = await store.list({
+  prefix: 'uploads/',
+  directories: true,
+})
+
+// Paginated iteration
+for await (const page of store.list({ paginate: true })) {
+  for (const blob of page.blobs) {
+    console.log(blob.key)
+  }
+}
+```
+
+**`ListOptions`:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `prefix` | `string` | Filter keys by prefix |
+| `directories` | `boolean` | Group by `/` delimiter |
+| `paginate` | `boolean` | Return `AsyncIterable` for page-by-page iteration |
+| `cursor` | `string` | Pagination cursor from previous response |
+| `limit` | `number` | Max entries per page |
+
+**`ListEntry`:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `key` | `string` | Blob key |
+| `etag` | `string` | Content hash |
+
+#### `delete(key: string): Promise<void>`
+
+Deletes a single blob. No error if the key does not exist.
+
+```typescript
+await store.delete('my-key')
+```
+
+## Storage Scopes
+
+### Site-Level Stores (`getStore`)
+
+Data persists across all deploys and is shared by all functions and builds for the site. Use for user data, application
+state, and any data that should survive redeployments.
+
+```typescript
+import { getStore } from '@netlify/blobs'
+
+const store = getStore('user-uploads')
+```
+
+### Deploy-Specific Stores (`getDeployStore`)
+
+Data is scoped to a single deploy. Use for build-generated data, pre-rendered content, or data that should be
+immutable after deploy. Build plugins and file-based uploads must write to deploy-specific stores.
+
+```typescript
+import { getDeployStore } from '@netlify/blobs'
+
+const store = getDeployStore()
+```
+
+**Production isolation pattern:** Use a global store in production and deploy store otherwise to prevent non-production
+data from polluting global stores:
+
+```typescript
+import { getStore, getDeployStore } from '@netlify/blobs'
+
+function getBlobStore(...storeOptions) {
+  if (Netlify.context?.deploy.context === 'production') {
+    return getStore(...storeOptions)
+  }
+  return getDeployStore(...storeOptions)
+}
+
+const store = getBlobStore('app-data')
+```
+
+## Consistency Models
+
+| Model | Default | Propagation | Use Case |
+|-------|---------|-------------|----------|
+| `eventual` | Yes | Up to 60 seconds | High-read workloads, caching |
+| `strong` | No | Immediate | Critical data, counters |
+
+Last-write-wins: concurrent writes to the same key result in the final write persisting. Add object-locking mechanisms
+if you need concurrency guarantees.
+
+```typescript
+// Strong consistency when you need immediate read-after-write
+const store = getStore({ name: 'counters', consistency: 'strong' })
+```
+
+## File-Based Uploads
+
+Deploy blobs by placing files in the `.netlify/blobs/deploy/` directory at build time. These are written to a
+deploy-specific store automatically.
+
+```
+.netlify/blobs/deploy/
+  my-key.txt              # Value stored with key "my-key.txt"
+  $my-key.txt.json        # Optional metadata for "my-key.txt"
+  nested/path/data.json   # Key is "nested/path/data.json"
+```
+
+**Metadata pattern:** Create a `$filename.json` sibling file:
+
+```json
+{
+  "contentType": "text/plain",
+  "author": "build-pipeline"
+}
+```
+
+Read file-based blobs in functions using `getDeployStore`:
+
+```typescript
+import { getDeployStore } from '@netlify/blobs'
+
+const store = getDeployStore()
+const data = await store.get('my-key.txt', { type: 'text' })
+```
+
+## Limits
+
+| Resource | Limit |
+|----------|-------|
+| Store name | 64 bytes |
+| Key | 600 bytes |
+| Object size | 5 GB |
+| Metadata per object | 64 KB |
+| Stores per site | Unlimited |
+| Objects per store | Unlimited |
+
+## Common Errors & Solutions
+
+### "Store not found" or empty reads
+
+**Cause:** Store name mismatch or reading from wrong scope.
+
+**Fix:**
+
+1. Verify the store name matches exactly (case-sensitive)
+2. Use `listStores()` to confirm the store exists
+3. Ensure you're using `getStore` for site-level data and `getDeployStore` for deploy-scoped data
+
+### "The environment has not been configured to use Netlify Blobs"
+
+**Cause:** Missing Blobs environment configuration in local development.
+
+**Fix:**
+
+1. Install the framework plugin (`@netlify/vite-plugin`, `@netlify/nuxt`, or `@netlify/vite-plugin-tanstack-start`)
+2. Deploy to Netlify or use the Vite plugin for local env configuration
+3. Ensure the site has at least one production deploy
+
+This does NOT apply to legacy V1 functions which require manual siteID/token configuration.
+
+### "Unauthorized" or permission errors
+
+**Cause:** Function is not running in a Netlify environment.
+
+**Fix:**
+
+1. Deploy to Netlify
+2. Ensure the site has at least one production deploy
+3. Confirm the function is deployed to Netlify (not a third-party host)
+
+### Stale reads after writing
+
+**Cause:** Default eventual consistency model (up to 60s propagation).
+
+**Fix:**
+
+1. Use strong consistency if immediate reads are required:
+   ```typescript
+   const store = getStore({ name: 'my-store', consistency: 'strong' })
+   ```
+2. Note that strong consistency has higher latency
+
+### Large object upload timeouts
+
+**Cause:** Object exceeds function timeout or network limits.
+
+**Fix:**
+
+1. Verify object is under 5 GB
+2. For large uploads, use file-based uploads via `.netlify/blobs/deploy/` at build time
+3. For function uploads, ensure function timeout is sufficient (background functions have 15-min timeout)