You're reading docs for Nextly Alpha. APIs may change between releases.

Plugins

Caching a plugin's data

Tag the cached reads built from a plugin's own data, and expire them when that data changes, on every instance, with no redeploy.

Caching a plugin's data

Alpha (0.x) — @experimental. ctx.cache and pluginCacheTag are new and ship @experimental: they work and are tested, but stay experimental until a first-party plugin expires its pages through them. Pin your nextly and @nextlyhq/plugin-sdk versions while you build on them.

When an entry or a Single changes, Nextly expires the cached reads of it by itself. A plugin's own data, such as its settings or a list of redirects, does not change through a content write, so a page built from it would stay cached until the next deploy. ctx.cache closes that gap: tag the reads built from your data, and expire the tag when the data changes.

Tag the read

ctx.cache.tag(part) gives the tag for one part of your plugin's data. Give it to whatever caches the read:

import type { PluginContext } from "@nextlyhq/plugin-sdk";
import { unstable_cache } from "next/cache";

// Your plugin's own read, from its settings or its own table.
declare function readDefaults(ctx: PluginContext): Promise<unknown>;

export function siteDefaults(ctx: PluginContext) {
  return unstable_cache(() => readDefaults(ctx), ["my-plugin", "defaults"], {
    tags: [ctx.cache.tag("defaults")],
  })();
}

A page that renders that read is expired with it. Code that renders your data outside your plugin's context, such as a route the app owns, spells the same tag with pluginCacheTag:

import { pluginCacheTag } from "@nextlyhq/plugin-sdk";

const tag = pluginCacheTag("my-plugin", "defaults");

Expire it when the data changes

await saveDefaults(values);
await ctx.cache.expire("defaults");

expire takes any number of parts, and expires each once. It goes through the same path as a content write's expiry, so every instance that shares the database serves the new value within a few seconds and a request.

What it guarantees

  • Your own tags only. Every tag is nextly:@plugin:{your plugin}:{part}. A plugin cannot expire a collection's, a Single's or another plugin's cached reads, and no content tag can be spelled like yours.
  • Never fails your write. Like the expiry after a content write, it is best-effort: a cache that cannot be reached is logged, and expire still resolves. A blank part is refused before anything is expired.
  • Long parts are hashed to stay within the length Next.js keeps, the same way on the read and on the expiry.