Drivers

Cloudflare

Store data in Cloudflare KV or R2 storage.


CloudFlare KV (binding)

Store data in Cloudflare KV and access from worker bindings.

Usage

Learn more about Cloudflare KV.

Note: This driver only works in a cloudflare worker environment, use cloudflare-kv-http for other environments.

You need to create and assign a KV. See KV Bindings for more information.

import { createStorage } from "unstorage";
import cloudflareKVBindingDriver from "unstorage/drivers/cloudflare-kv-binding";

// Using binding name to be picked from globalThis
const storage = createStorage({
  driver: cloudflareKVBindingDriver({ binding: "STORAGE" }),
});

// Directly setting binding
const storage = createStorage({
  driver: cloudflareKVBindingDriver({ binding: globalThis.STORAGE }),
});

// Using from Durable Objects and Workers using Modules Syntax
const storage = createStorage({
  driver: cloudflareKVBindingDriver({ binding: this.env.STORAGE }),
});

// Using outside of Cloudflare Workers (like Node.js)
// Use cloudflare-kv-http

Options:

  • binding: KV binding or name of namespace. Default is STORAGE.
  • base: Adds prefix to all stored keys

Cloudflare KV (http)

Store data in Cloudflare KV using the Cloudflare API v4.

Usage

Learn more about Cloudflare KV API.

You need to create a KV namespace. See KV Bindings for more information.

Note: This driver uses native fetch and works universally! For using directly in a cloudflare worker environment, please use cloudflare-kv-binding driver for best performance!

import { createStorage } from "unstorage";
import cloudflareKVHTTPDriver from "unstorage/drivers/cloudflare-kv-http";

// Using `apiToken`
const storage = createStorage({
  driver: cloudflareKVHTTPDriver({
    accountId: "my-account-id",
    namespaceId: "my-kv-namespace-id",
    apiToken: "supersecret-api-token",
  }),
});

// Using `email` and `apiKey`
const storage = createStorage({
  driver: cloudflareKVHTTPDriver({
    accountId: "my-account-id",
    namespaceId: "my-kv-namespace-id",
    email: "me@example.com",
    apiKey: "my-api-key",
  }),
});

// Using `userServiceKey`
const storage = createStorage({
  driver: cloudflareKVHTTPDriver({
    accountId: "my-account-id",
    namespaceId: "my-kv-namespace-id",
    userServiceKey: "v1.0-my-service-key",
  }),
});

Options:

  • accountId: Cloudflare account ID.
  • namespaceId: The ID of the KV namespace to target. Note: be sure to use the namespace's ID, and not the name or binding used in a worker environment.
  • apiToken: API Token generated from the User Profile 'API Tokens' page.
  • email: Email address associated with your account. May be used along with apiKey to authenticate in place of apiToken.
  • apiKey: API key generated on the "My Account" page of the Cloudflare console. May be used along with email to authenticate in place of apiToken.
  • userServiceKey: A special Cloudflare API key good for a restricted set of endpoints. Always begins with "v1.0-", may vary in length. May be used to authenticate in place of apiToken or apiKey and email.
  • apiURL: Custom API URL. Default is https://api.cloudflare.com.
  • base: Adds prefix to all stored keys

Supported methods:

  • getItem: Maps to Read key-value pair GET accounts/:account_identifier/storage/kv/namespaces/:namespace_identifier/values/:key_name
  • hasItem: Maps to Read key-value pair GET accounts/:account_identifier/storage/kv/namespaces/:namespace_identifier/values/:key_name. Returns true if <parsed response body>.success is true.
  • setItem: Maps to Write key-value pair PUT accounts/:account_identifier/storage/kv/namespaces/:namespace_identifier/values/:key_name
  • removeItem: Maps to Delete key-value pair DELETE accounts/:account_identifier/storage/kv/namespaces/:namespace_identifier/values/:key_name
  • getKeys: Maps to List a Namespace's Keys GET accounts/:account_identifier/storage/kv/namespaces/:namespace_identifier/keys
  • clear: Maps to Delete key-value pair DELETE accounts/:account_identifier/storage/kv/namespaces/:namespace_identifier/bulk

CloudFlare R2 (binding)

Store data in Cloudflare R2 buckets and access from worker bindings.

This is an experimental driver! This driver only works in a cloudflare worker environment and cannot be used in other runtime environments such as Node.js (r2-http driver is coming soon)
Learn more about Cloudflare R2 buckets.

You need to create and assign a R2 bucket. See R2 Bindings for more information.

import { createStorage } from "unstorage";
import cloudflareR2BindingDriver from "unstorage/drivers/cloudflare-r2-binding";

// Using binding name to be picked from globalThis
const storage = createStorage({
  driver: cloudflareR2BindingDriver({ binding: "BUCKET" }),
});

// Directly setting binding
const storage = createStorage({
  driver: cloudflareR2BindingDriver({ binding: globalThis.BUCKET }),
});

// Using from Durable Objects and Workers using Modules Syntax
const storage = createStorage({
  driver: cloudflareR2BindingDriver({ binding: this.env.BUCKET }),
});

Options:

  • binding: Bucket binding or name. Default is BUCKET.
  • base: Prefix all keys with base.