Skip to Content
Documentation

Cache

Cache API data

Cache a slow database read in a VitNode Hono route with a typed defineCacheEntry (name, version, key and Zod schema) and delete it when the data changes.

The API cache keeps the result of a slow read, such as a count over a large table, so it runs once for many visitors instead of once per request. Every cached value is a cache entry: defineCacheEntry declares its key, its Zod schema and how long it lives, and c.get("cache").entry(definition, ...key) reads and writes it. Reads come back typed and validated, and writes are checked before they are stored. In this guide the site-notes plugin caches how many notes were written in a given year.

Before you begin

  • The site-notes plugin with its site_notes table from Database, and the create route from Permissions.
  • Optional: Redis. Without it, entries live in a per-process memory store for at most 15 seconds, so the same code works with and without Redis, but a delete on one instance never reaches the others.

Define the entry

Create src/api/cache/year-stats.cache.ts. defineCacheEntry comes from the plugin's src/api/builders.ts, which binds it to your plugin id:

plugins/site-notes/src/api/cache/year-stats.cache.ts
import { z } from "zod";

import { defineCacheEntry } from "@/api/builders";

export const yearStatsCache = defineCacheEntry({
  name: "year-stats",
  version: 1,
  key: (year: number) => [year],
  schema: z.object({
    notes: z.number().int().nonnegative(),
    lastNoteAt: z.iso.datetime().nullable(),
  }),
  ttlSeconds: 300,
});
  • key turns the entry's arguments into key parts. Its parameters become the arguments of entry(), so year must be a number wherever the entry is used. Omit key for an entry with a single value.
  • schema checks every write and every read. Values are stored as JSON, so its input must be JSON: z.iso.datetime() instead of z.date().
  • version is yours to bump when the stored shape or its meaning changes. See Change a cache entry.
  • The entry belongs to site-notes, whichever plugin's request reads it, so a listener running in a core request reaches the same key.

Read through the entry

Create src/api/modules/notes/routes/year-stats.route.ts. The handler wraps the query in remember:

plugins/site-notes/src/api/modules/notes/routes/year-stats.route.ts
import { z } from "@hono/zod-openapi";
import { and, count, gte, lt, max } from "drizzle-orm";

import { buildRoute } from "@/api/builders";
import { yearStatsCache } from "@/api/cache/year-stats.cache";
import { site_notes } from "@/database/notes";

export const yearStatsRoute = buildRoute({
  route: {
    method: "get",
    path: "/stats/{year}",
    request: {
      params: z.object({ year: z.coerce.number().int().min(2000).max(9999) }),
    },
    responses: {
      200: {
        content: { "application/json": { schema: yearStatsCache.schema } },
        description: "How many notes were written in the year, and when the last one was.",
      },
    },
  },
  handler: async c => {
    const { year } = c.req.valid("param");
    const stats = await c
      .get("cache")
      .entry(yearStatsCache, year)
      .remember(async () => {
        const [row] = await c
          .get("db")
          .select({ notes: count(), lastNoteAt: max(site_notes.createdAt) })
          .from(site_notes)
          .where(
            and(
              gte(site_notes.createdAt, new Date(Date.UTC(year, 0, 1))),
              lt(site_notes.createdAt, new Date(Date.UTC(year + 1, 0, 1))),
            ),
          );

        return {
          notes: row?.notes ?? 0,
          lastNoteAt: row?.lastNoteAt?.toISOString() ?? null,
        };
      });

    return c.json(stats, 200);
  },
});

Then add yearStatsRoute to the routes of notesModule in src/api/modules/notes/notes.module.ts.

On a hit, remember returns the stored value parsed by the schema and skips the query. On a miss, it runs the loader, validates the result, stores it for 300 seconds and returns the parsed value. A loader result the schema rejects throws CacheEntryValidationError and nothing is stored, so a bug in the query surfaces instead of being cached.

Expire the entry after a write

A new note changes the current year's count. In src/api/modules/admin/notes/routes/create.route.ts, import the entry with import { yearStatsCache } from "@/api/cache/year-stats.cache"; and delete it after the insert:

plugins/site-notes/src/api/modules/admin/notes/routes/create.route.ts
  handler: async c => {
    const values = c.req.valid("json");
    const [note] = await c
      .get("db")
      .insert(site_notes)
      .values(values)
      .returning({ id: site_notes.id, title: site_notes.title, body: site_notes.body });

    await c
      .get("cache")
      .entry(yearStatsCache, new Date().getUTCFullYear())
      .delete();

    return c.json(note, 201);
  },

Do the same in any other route that adds or removes notes. The TTL is a safety net, not the invalidation: without delete, the old count stays for up to five minutes. When the write runs in a transaction, delete after it commits.

delete() cannot stop a request that loaded the old value just before the commit from storing it again right after the delete. For a count that may be off for a few minutes that is acceptable; when a list must show a write as soon as it commits, cache it under a generation instead.

The API cache is shared by every visitor

An entry returns the same value to everyone who asks with the same key. For data that depends on who is asking, put the user id in the key, for example key: (userId: number) => [userId], or do not cache it.

Check the result

  1. Open http://localhost:3000/api/site-notes/notes/stats/2026, using the year your demo notes were added. It answers {"notes":3,"lastNoteAt":"…"}.

  2. With Redis connected, list the plugin's entries:

    redis-cli --scan --pattern 'vitnode:cache-entry:site-notes:*'

    The output includes vitnode:cache-entry:site-notes:year-stats:v1:[2026]. Calling the URL again within five minutes does not run the query.

  3. Create a note, from the AdminCP page or the test button in Permissions, and run the command again. The key is gone until the next request, which then counts the new note.

AdminCP → System → Integrations (/admin/core/system/integrations) shows whether Redis is connected: the Redis card says Active, or Needs attention when it is configured but unreachable.