Hooks
Run your code before and after reads, writes and deletes, in a defined order.
This page lists every collection and field hook, the order they run in and what each may return.
Collection hooks
Set hooks on a collection. Each hook can be a function or an array of functions, which run in order.
import { collection, fields as f } from '@kitcms/core';
export const posts = collection({
slug: 'posts',
access: { read: () => true },
hooks: {
beforeChange: ({ data, operation, req }) => {
if (operation === 'create' && req.user) return { ...data, author: req.user.id };
},
afterChange: ({ doc, req }) => {
req.context.changed = doc.id;
},
afterRead: ({ doc }) => ({ ...doc, title: doc.title.trim() }),
},
fields: {
title: f.text({ required: true }),
author: f.text(),
},
});| Hook | Arguments | May return |
|---|---|---|
beforeValidate |
{ req, operation, data, originalDoc? } |
A replacement data (or a partial), or nothing. |
beforeChange |
{ req, operation, data, originalDoc? } |
A replacement data, or nothing. |
afterChange |
{ req, operation, doc, previousDoc? } |
A replacement doc, or nothing. |
beforeRead |
{ req, doc } |
A replacement doc, or nothing. |
afterRead |
{ req, doc } |
A replacement doc, or nothing. |
beforeDelete |
{ req, id, doc } |
Nothing. Throw to stop the delete. |
afterDelete |
{ req, id, doc } |
Nothing. |
operation is 'create' or 'update'. Returning nothing keeps the input. When a hook returns a value, the next hook receives it. Globals take the same hooks except the delete ones.
Keys that hooks add to data and that are not fields never reach D1.
Order
Create and update
- Access check, then field write access.
- Defaults and slug filling.
- Collection
beforeValidate, then fieldbeforeValidate. - Validation.
- Field
beforeChange, then collectionbeforeChange. - D1 write.
- Field
afterChange, then collectionafterChange. - The read steps below, for the returned document.
Read
- Access check and D1 query.
- Collection
beforeRead. - Field read access (denied fields are removed).
- Field
afterRead. - The file
urlis computed for upload collections. - Collection
afterRead. - Relationship population, when you ask for
depth.
Delete
- Access check.
beforeDelete.- D1 delete. This fails if other documents still reference the document.
afterDelete.
Read hooks run for every document a find returns, so keep them cheap.
Field hooks
Fields take hooks with beforeValidate, beforeChange, afterChange and afterRead.
slugified: f.text({
hooks: {
beforeChange: ({ value }) => (typeof value === 'string' ? value.toLowerCase() : value),
},
}),A field hook gets { req, operation, value, originalDoc?, data, siblingData }. Return a new value, or nothing to keep it. Containers run before their children, and field hooks reach into groups, array rows and blocks.
req
Every hook receives the operation's req:
| Property | What it is |
|---|---|
user |
The caller, or null. |
source |
'local', 'admin', 'rpc' or 'rest'. |
context |
A free-form object shared by every hook of one operation. |
cms |
The Local API, acting as the same user. |
event |
The SvelteKit request, when there is one. |
Call the Local API from a hook
Pass { req } to nested calls. They then share the user and context, so your access rules and hooks see the same caller:
afterChange: async ({ doc, req }) => {
await req.cms.update('stats', 'posts', { count: 1 }, { req });
},Nested writes run the full pipeline too, so they can trigger hooks of their own. Guard against loops with req.context:
afterChange: async ({ doc, req }) => {
if (req.context.fromPostHook) return;
await req.cms.update('audit', auditId, { last: doc.id }, { req, context: { fromPostHook: true } });
},Errors
Throw ValidationError, ForbiddenError or NotFoundError from @kitcms/core in a hook and every entry point maps it to the same response: a field error in the admin, 400, 403 or 404 over REST and a typed error over RPC.
import { ForbiddenError } from '@kitcms/core';
beforeDelete: ({ doc }) => {
if (doc.locked) throw new ForbiddenError('This document is locked.');
},