TanStarter DocsCache
Learn how to set up and use Cloudflare KV for server-side caching
TanStarter uses Cloudflare KV for server-side JSON caching. It is useful for read-heavy data such as provider status checks, public lists, and expensive API responses that can be refreshed after a short TTL.
Cloudflare KV is eventually consistent. Do not use the Cache module as the source of truth for payments, authentication, credits, quotas, or other strongly consistent state.
Setup
Configure Cloudflare API Token
Please complete the Cloudflare configuration first, ensuring the Token includes Account > Workers KV Storage > Edit permission.
Create KV Namespace
You can create a KV namespace via the Cloudflare Dashboard or Wrangler CLI:
- Create a new KV namespace:
pnpm wrangler kv namespace create CACHE- Copy the returned
id.
- Log in to the Cloudflare Dashboard
- Go to Storage & Databases > KV
- Click Create namespace
- Enter the namespace name, for example
CACHE - Copy the namespace ID after creation
Configure Wrangler Binding
Configure the KV namespace binding in wrangler.jsonc:
{
"kv_namespaces": [
{
"binding": "CACHE",
"id": "your-kv-namespace-id" // Change to your KV namespace ID
}
]
}The Worker receives this namespace as env.CACHE.
Update Website Configuration
In most cases, the default configuration works fine. If you need to change it, modify the cache config in src/config/website.ts:
export const websiteConfig = {
// ...other config
cache: {
enable: true,
provider: 'kv',
},
// ...other config
}If you are setting up your environment, you can go back to the Environment Configuration doc and continue. The rest of this document can be read later.
Environment Configuration
Review Worker bindings
Core Features
- Server-side JSON cache helpers
- Cloudflare KV provider
- TTL-based expiration
- Stable cache key generation
- Single-key and prefix-based invalidation
- Graceful fallback to the original fetcher when cache is disabled or unavailable
Usage
Basic Cache Operations
TanStarter provides simple APIs for common cache operations:
import {
CACHE_TTL,
createCacheKey,
deleteCache,
getOrSetCache,
} from '@/cache';
const key = createCacheKey('newsletter:status', email);
const status = await getOrSetCache({
key,
ttlSeconds: CACHE_TTL.newsletterStatus,
fetcher: () => newsletterProvider.checkSubscribeStatus({ email }),
});
await deleteCache(key);Prefix Invalidation
Use prefix invalidation for list-style caches or grouped keys:
import { createCacheKey, deleteCacheByPrefix } from '@/cache';
const prefix = createCacheKey('products:list');
await deleteCacheByPrefix(prefix);Current Usage
The built-in newsletter module can use the Cache module to cache subscription status checks. After subscribe or unsubscribe operations, the related cache key is deleted so the next status check fetches fresh data.
Best Practices
- Cache read-heavy data: Use cache for data that is safe to serve slightly stale
- Set clear TTLs: Keep TTL values in
src/cache/constants.ts - Invalidate after writes: Delete affected cache keys after mutations
- Keep keys stable: Use
createCacheKey()instead of manually concatenating strings
Next Steps
Now that you understand how to use server-side caching in TanStarter, explore these related topics: