Store data at the edge

An AEM Edge Function often needs to keep data at the edge, close to your visitors, and reuse it across function invocations without a round trip to origin. AEM Edge Functions provide this edge data storage through a KV store.

A KV store is a key-value store that you read and write at runtime. Its data persists between function invocations, so any part of your AEM Edge Function code can read what another part wrote earlier. Use it to cache computed results, hold redirect maps, or share data across requests.

When to use a KV store

Unlike configs, which you set at deploy time and read only, a KV store is read and written at runtime. One kv_default store is provisioned for your AEM Edge Function, and any of its modules or endpoints can read and write to it.

Enable the KV store

Set kvs: true under data in edgeFunctions.yaml, as a sibling of functions. This one toggle provisions the kv_default store for the AEM Edge Function.

# config/edgeFunctions.yaml
kind: "EdgeFunctions"
version: "1"
data:
  functions:
    - name: my-edge-function
  kvs: true # enable the KV store

Deploy the updated configuration through the Cloud Manager config pipeline, or with aio aem rde:install -t env-config ./config on an RDE. See Set up AEM Edge Functions on AEM as a Cloud Service or Set up AEM Edge Functions on Edge Delivery Services for more details.

Read and write in code

Open the kv_default store, then call get(key) and put(key, value, options?). Both calls are asynchronous. Values are stored as strings, so serialize objects with JSON.stringify() on write. On read, the entry returned by get(key) exposes text(), json(), and arrayBuffer(), so call entry.json() to parse a stored object.

// src/index.js or handler file
import { KVStore } from "fastly:kv-store";

// open the KV store
const kv = new KVStore("kv_default");

// write a value (serialize objects to a string)
await kv.put("greeting", JSON.stringify({ text: "Hello from the edge" }));

// read a value (get returns an entry, or null when the key is missing)
const entry = await kv.get("greeting");
const value = entry ? await entry.json() : null;

Cache data with a KV store

A common pattern is cache-aside. The handler reads from the KV store first, and calls the backend only on a miss. Pass a ttl (in seconds) to put() and the store expires the entry for you, so you do not track expiry yourself.

// src/lib/cache.js
import { KVStore } from "fastly:kv-store";

const kv = new KVStore("kv_default");

// Read a cached value, or null when the key is missing or expired
export async function getCached(key) {
  const entry = await kv.get(key);
  return entry ? await entry.json() : null;
}

// Cache a value; the store expires it after ttlSeconds
export async function setCached(key, payload, ttlSeconds) {
  await kv.put(key, JSON.stringify(payload), { ttl: ttlSeconds });
}

In a handler, read the cache, fall back to the backend on a miss, then write the result back.

let data = await getCached("inventory:west");
if (!data) {
  data = await fetchFromBackend();
  await setCached("inventory:west", data, 60); // store expires the entry after 60 seconds
}

Populate the KV store

The KV store has no deploy-time seeding in edgeFunctions.yaml. Your function code writes every value at runtime. Two common approaches are:

Guidelines

Complete example

The AEM Edge Functions examples repository includes a KV store example with full config/ and code:

Additional resources