Caching overview

Avoid repeated lookups by reusing values your app has already loaded.

A cache temporarily stores a value so later requests can reuse it without repeating the original work. Product prices, search results, and calculated summaries are common examples. Keep the original data in your database or another source you can read again.

Use caching when a lookup is expensive and a slightly older result is acceptable. Skip it when every request must see the latest value.

Pre-setup

Use Redis in local Docker. Start from an existing RELKIT app and a running Docker daemon.

Install Redis and Docker support

From this guide’s application/package root, install only its selected requirements:

bun add @relkit/docker@0.7.12 @relkit/redis@0.8.1

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in dependencies; build/type tooling belongs in devDependencies. Installing an adapter does not supply its optional SDK peers or enable the feature’s configuration.

Configure the requests profile

/** Local Redis supplies the connection for the requests cache profile. */
import { defineApp, defineEnv } from "@relkit/app/config";
import { docker } from "@relkit/docker";
import { redis } from "@relkit/redis";

export default defineApp({
  env: defineEnv({}),
  cache: { requests: docker(redis()) },
  defaults: { cache: "requests" },
});

The examples use profile: "requests". Docker supplies the Redis connection; this path adds no defineEnv fields. If a scaffold used a different profile, align its profile with this configuration. Connected Redis uses an explicit secret binding.

Check and start after defining the cache

Check Docker before continuing. After adding the resource and its service registration, run from the app root:

docker version
bun run check
bun run typecheck
bun run dev

check validates the graph; it starts no containers. dev starts only Docker recipes used by that graph, waits for readiness, and binds their generated connection values. An unused profile alone does not start a container. Keep the server running and use bun run relkit local status in another terminal to inspect the services. Local Docker covers detached startup and stopping services while retaining their volumes.

The Caching API

Usually, caching means connecting a Redis client, choosing keys, serializing values, and checking for missing entries. With RELKIT, define the key and value shapes, give your function access, and use getOrSet() to load missing values.

API	What you use it for
`defineCache`	Define the cache’s keys, values, and expiration time.
`dependencies.cache`	Give a function access to a cache.
`context.cache.prices.getOrSet(key, load)`	Reuse a saved value or load and save it when missing.
`context.cache.prices.set(key, value)`	Save or replace a value.
`context.cache.prices.delete(key)`	Remove a value so the next lookup can load fresh data.

You can use caches in event functions too, and in ordinary functions called by jobs and tools.

Try it in your app

Follow the cached-price example for the first working cache. It runs with Docker Redis and no cloud credentials. Use Define a cache when you need to choose keys, values, and expiration for your own data.

After the separate Inspector setup, open Cache and select your cache to see keys and their remaining lifetime. Choose View value to inspect a saved value.