Revalidating

A numeric revalidate value automatically enables cached SSR and gives the cached output a lifetime in seconds. After it expires, the next resolution produces fresh output and replaces the stored entry.

Choose the route-aware helper when you want typed path parameters and the route contract in one object. Choose named exports when you want each behavior visible at module scope. Both examples describe the same revalidated project route.

tsximport { defineRoutePage } from "@tavojs/core/router";
import { Page, Text } from "@tavojs/ui";

type Project = { id: string; name: string };

function getProject(id: string): Project {
  return { id, name: `Project ${id}` };
}

export default defineRoutePage<"/projects/[id]", Project>("/projects/[id]", {
  revalidate: 300,

  cacheTags: ({ params }) => ["projects", `project:${params.id}`],

  load: ({ params }) => getProject(params.id),

  default: function ProjectPage({ data }) {
    return (
      <Page>
        <Text>{data?.name}</Text>
      </Page>
    );
  },
});

tsximport type { PageLoadContext, PageProps } from "@tavojs/core/router";
import { Page, Text } from "@tavojs/ui";

type Project = { id: string; name: string };
type ProjectParams = { id: string };

function getProject(id: string): Project {
  return { id, name: `Project ${id}` };
}

export const revalidate = 300;
export const cacheTags = ({ params }: PageLoadContext) => [
  "projects",
  `project:${params.id}`,
];

export function load({ params }: PageLoadContext): Project {
  return getProject(params.id);
}

export default function ProjectPage({
  data,
}: PageProps<Project, ProjectParams>) {
  return (
    <Page>
      <Text>{data?.name}</Text>
    </Page>
  );
}

cacheTags attaches application-owned names to a route entry. Tags can be static or derived from route parameters, which lets one mutation target a collection, one record, or both.

• Use stable domain names such as projects and project:42.

• Do not put secrets or personal data into a tag.

• Keep tag production beside the route data contract so readers can see what invalidates it.

PagesRuntime exposes synchronous tag invalidation for its resolved-route cache. The Node request handler exposes asynchronous invalidateCache for both runtime and static adapter entries. Custom cache adapters may also implement invalidateTags.

tstype CacheInvalidator = {
  invalidateCache(tags: string[]): Promise<number>;
};

export async function invalidateProjectCache(
  requestHandler: CacheInvalidator,
  projectId: string,
) {
  return requestHandler.invalidateCache(["projects", `project:${projectId}`]);
}

Trigger invalidation after the database or external write succeeds. If the mutation and cache live in different systems, record enough information to retry failed invalidation without repeating the business change.