Collection Hooks

Collection Hooks are Hooks that run on Documents within a specific Collection. They allow you to execute your own logic during specific events of the Document lifecycle. To add Hooks to a Collection, use the hooks property in your Collection Config:

import type { CollectionConfig } from 'frogbot'

export const CollectionWithHooks: CollectionConfig = {
  // ...
  hooks: {
    // ...
  },
}

You can also set hooks on the field-level to isolate hook logic to specific fields. More details.

Config Options

All Collection Hooks accept an array of synchronous or asynchronous functions. Each Collection Hook receives specific arguments based on its own type, and has the ability to modify specific outputs.

import type { CollectionConfig } from 'frogbot';

export const CollectionWithHooks: CollectionConfig = {
  // ...
  hooks: {
    beforeOperation: [(args) => {...}],
    beforeValidate: [(args) => {...}],
    beforeDelete: [(args) => {...}],
    beforeChange: [(args) => {...}],
    beforeRead: [(args) => {...}],
    afterChange: [(args) => {...}],
    afterRead: [(args) => {...}],
    afterDelete: [(args) => {...}],
    afterOperation: [(args) => {...}],
    afterError: [(args) => {....}],

    // Auth-enabled Hooks
    beforeLogin: [(args) => {...}],
    afterLogin: [(args) => {...}],
    afterLogout: [(args) => {...}],
    afterRefresh: [(args) => {...}],
    afterMe: [(args) => {...}],
    afterForgotPassword: [(args) => {...}],
    refresh: [(args) => {...}],
    me: [(args) => {...}],
  },
}

Option	Type	Default	Description
`beforeOperation`	`CollectionBeforeOperationHook[]`	`[]`	Runs before any operation. Can replace the operation’s arguments. More details.
`beforeValidate`	`CollectionBeforeValidateHook[]`	`[]`	Runs on `create` and `update` before validation. Can change the data. More details.
`beforeChange`	`CollectionBeforeChangeHook[]`	`[]`	Runs on `create` and `update` after validation. Can change the data. More details.
`afterChange`	`CollectionAfterChangeHook[]`	`[]`	Runs after a document is created or updated. Can change the returned document. More details.
`beforeRead`	`CollectionBeforeReadHook[]`	`[]`	Runs before a document is returned, before field hooks. More details.
`afterRead`	`CollectionAfterReadHook[]`	`[]`	Runs before a document is returned, after field hooks. More details.
`beforeDelete`	`CollectionBeforeDeleteHook[]`	`[]`	Runs before a document is deleted. More details.
`afterDelete`	`CollectionAfterDeleteHook[]`	`[]`	Runs after a document is deleted. More details.
`afterOperation`	`CollectionAfterOperationHook[]`	`[]`	Runs after any operation. Can replace the result. More details.
`afterError`	`CollectionAfterErrorHook[]`	`[]`	Runs when a request on this collection fails. More details.
`beforeLogin`	`CollectionBeforeLoginHook[]`	`[]`	Auth collections only. Runs before a login succeeds. More details.
`afterLogin`	`CollectionAfterLoginHook[]`	`[]`	Auth collections only. Runs after a login succeeds. More details.
`afterLogout`	`CollectionAfterLogoutHook[]`	`[]`	Auth collections only. Runs after a logout. More details.
`afterMe`	`CollectionAfterMeHook[]`	`[]`	Auth collections only. Runs after the `me` operation. More details.
`afterRefresh`	`CollectionAfterRefreshHook[]`	`[]`	Auth collections only. Runs after a token is refreshed. More details.
`afterForgotPassword`	`CollectionAfterForgotPasswordHook[]`	`[]`	Auth collections only. Runs after a forgot password request succeeds. More details.
`refresh`	`CollectionRefreshHook[]`	`[]`	Auth collections only. Can replace the `refresh` operation. More details.
`me`	`CollectionMeHook[]`	`[]`	Auth collections only. Can replace the `me` operation. More details.

beforeOperation

The beforeOperation hook can be used to modify the arguments that operations accept or execute side-effects that run before an operation begins.

import type { CollectionBeforeOperationHook } from 'frogbot'

const beforeOperationHook: CollectionBeforeOperationHook = async ({
  args,
  operation,
  req,
}) => {
  return args // return modified operation arguments as necessary
}

The following arguments are provided to the beforeOperation hook:

Option	Type	Default	Description
`collection`	`SanitizedCollectionConfig`	Always set	The Collection in which this Hook is running against.
`context`	`RequestContext`	Always set	Custom context passed between Hooks. More details.
`req`	`FrogBotRequest`	Always set	The request, with the signed-in `user` and `req.frogbot`. For Local API operations without a `req`, FrogBot creates one.
`operation`	`string`	Always set	The operation about to run, such as `'create'`, `'find'`, `'findByID'`, `'update'`, `'updateByID'`, `'delete'`, `'deleteByID'`, `'count'`, `'login'`, or `'forgotPassword'`. Some operations also report the older names `'read'` and `'readDistinct'`.
`args`	`object`	Always set	The arguments the operation was called with. Return a changed copy to replace them.
`overrideAccess`	`boolean`	—	Whether the operation skips access control.

beforeValidate

Runs during the create and update operations. This hook allows you to add or format data before the incoming data is validated server-side. Please do note that this does not run before client-side validation. If you render a custom field component in your front-end and provide it with a validate function, the order that validations will run in is:

validate runs on the client
if successful, beforeValidate runs on the server
validate runs on the server

import type { CollectionBeforeValidateHook } from 'frogbot'
import type { Post } from '@/frogbot-types'

const beforeValidateHook: CollectionBeforeValidateHook<Post> = async ({
  data, // Typed as Partial<Post>
}) => {
  return data
}

The following arguments are provided to the beforeValidate hook:

Option	Type	Default	Description
`collection`	`SanitizedCollectionConfig`	Always set	The Collection in which this Hook is running against.
`context`	`RequestContext`	Always set	Custom context passed between Hooks. More details.
`data`	`object`	—	The incoming data passed through the operation.
`operation`	`'create' \| 'update'`	Always set	The name of the operation that this hook is running within.
`originalDoc`	`object`	—	The full document before changes are applied. Present on updates; undefined on creates. Use this to read the document id and any unchanged fields.
`req`	`FrogBotRequest`	Always set	The request, with the signed-in `user` and `req.frogbot`. For Local API operations without a `req`, FrogBot creates one.

Why isn’t id in data? data only represents the delta you’re saving. Read originalDoc.id during updates, and prefer afterChange if you need the id during creates

On update operations, data contains only the fields being changed. It may omit id and any unchanged fields. Use originalDoc to read existing values. On create, data is the new submission and the document id is not yet available at this stage.

beforeChange

Immediately before validation, beforeChange hooks will run during create and update operations. At this stage, the data should be treated as unvalidated user input. There is no guarantee that required fields exist or that fields are in the correct format. As such, using this data for side effects requires manual validation. You can optionally modify the shape of the data to be saved.

import type { CollectionBeforeChangeHook } from 'frogbot'

export const requireTitleOnUpdate: CollectionBeforeChangeHook = async ({
  data, // Partial<T> — changed fields only
  originalDoc, // Full doc before changes (defined on update)
  operation, // 'create' | 'update'
}) => {
  // Need the id? Don't expect it in `data`.
  const id = operation === 'update' ? originalDoc.id : undefined

  // Example: enforce that title cannot be cleared on update
  if (operation === 'update' && 'title' in (data ?? {}) && !data.title) {
    throw new Error(`Document ${id} must have a title`)
  }

  return data
}

The following arguments are provided to the beforeChange hook:

Option	Type	Default	Description
`collection`	`SanitizedCollectionConfig`	Always set	The Collection in which this Hook is running against.
`context`	`RequestContext`	Always set	Custom context passed between Hooks. More details.
`data`	`object`	Always set	The incoming data passed through the operation.
`operation`	`'create' \| 'update'`	Always set	The name of the operation that this hook is running within.
`originalDoc`	`object`	—	The full document before changes are applied. Present on updates; undefined on creates. Use this to read the document id and any unchanged fields.
`req`	`FrogBotRequest`	Always set	The request, with the signed-in `user` and `req.frogbot`. For Local API operations without a `req`, FrogBot creates one.

Why isn’t id in data? data only represents the delta you’re saving. Read originalDoc.id during updates, and prefer afterChange if you need the id during creates

afterChange

After a document is created or updated, the afterChange hook runs. This hook is helpful for recalculating statistics, syncing user profile changes to a CRM, and more.

import type { CollectionAfterChangeHook } from 'frogbot'
import type { Post } from '@/frogbot-types'

const afterChangeHook: CollectionAfterChangeHook<Post> = async ({
  doc, // Typed as Post
  previousDoc, // Typed as Post
}) => {
  return doc
}

The following arguments are provided to the afterChange hook:

Option	Type	Default	Description
`collection`	`SanitizedCollectionConfig`	Always set	The Collection in which this Hook is running against.
`context`	`RequestContext`	Always set	Custom context passed between Hooks. More details.
`data`	`object`	Always set	The incoming data passed through the operation.
`doc`	`object`	Always set	The resulting Document after changes are applied.
`operation`	`'create' \| 'update'`	Always set	The name of the operation that this hook is running within.
`previousDoc`	`object`	Always set	The Document before changes were applied.
`overrideAccess`	`boolean`	—	Whether the operation skips access control.
`req`	`FrogBotRequest`	Always set	The request, with the signed-in `user` and `req.frogbot`. For Local API operations without a `req`, FrogBot creates one.
`select`	`SelectType`	—	The field selection the operation’s response uses.

beforeRead

Runs before find and findByID operations are transformed for output by afterRead. This hook fires before hidden fields are removed and before localized fields are flattened into the requested locale. Using this Hook will provide you with all locales and all hidden fields via the doc argument.

import type { CollectionBeforeReadHook } from 'frogbot'
import type { Post } from '@/frogbot-types'

const beforeReadHook: CollectionBeforeReadHook<Post> = async ({
  doc, // Typed as Post
}) => {
  return doc
}

The following arguments are provided to the beforeRead hook:

Option	Type	Default	Description
`collection`	`SanitizedCollectionConfig`	Always set	The Collection in which this Hook is running against.
`context`	`RequestContext`	Always set	Custom context passed between Hooks. More details.
`doc`	`object`	Always set	The Document as read from the database, before field hooks and access control run.
`query`	`Record<string, any>`	Always set	The Query of the request.
`overrideAccess`	`boolean`	—	Whether the operation skips access control.
`req`	`FrogBotRequest`	Always set	The request, with the signed-in `user` and `req.frogbot`. For Local API operations without a `req`, FrogBot creates one.

afterRead

Runs as the last step before documents are returned. Flattens locales, hides protected fields, and removes fields that users do not have access to.

import type { CollectionAfterReadHook } from 'frogbot'
import type { Post } from '@/frogbot-types'

const afterReadHook: CollectionAfterReadHook<Post> = async ({
  doc, // Typed as Post
}) => {
  return doc
}

The following arguments are provided to the afterRead hook:

Option	Type	Default	Description
`collection`	`SanitizedCollectionConfig`	Always set	The Collection in which this Hook is running against.
`context`	`RequestContext`	Always set	Custom context passed between Hooks. More details.
`doc`	`object`	Always set	The Document after field hooks and access control run.
`query`	`Record<string, any>`	—	The Query of the request.
`findMany`	`boolean`	—	`true` when the document is one of several returned, such as from `find`.
`overrideAccess`	`boolean`	—	Whether the operation skips access control.
`req`	`FrogBotRequest`	Always set	The request, with the signed-in `user` and `req.frogbot`. For Local API operations without a `req`, FrogBot creates one.

beforeDelete

Runs before the delete operation. Returned values are discarded.

import type { CollectionBeforeDeleteHook } from 'frogbot';

const beforeDeleteHook: CollectionBeforeDeleteHook = async ({
  req,
  id,
}) => {...}

The following arguments are provided to the beforeDelete hook:

Option	Type	Default	Description
`collection`	`SanitizedCollectionConfig`	Always set	The Collection in which this Hook is running against.
`context`	`RequestContext`	Always set	Custom context passed between Hooks. More details.
`id`	`string \| number`	Always set	The ID of the Document being deleted.
`req`	`FrogBotRequest`	Always set	The request, with the signed-in `user` and `req.frogbot`. For Local API operations without a `req`, FrogBot creates one.

afterDelete

Runs immediately after the delete operation removes records from the database. Returned values are discarded.

import type { CollectionAfterDeleteHook } from 'frogbot';

const afterDeleteHook: CollectionAfterDeleteHook = async ({
  req,
  id,
  doc,
}) => {...}

The following arguments are provided to the afterDelete hook:

Option	Type	Default	Description
`collection`	`SanitizedCollectionConfig`	Always set	The Collection in which this Hook is running against.
`context`	`RequestContext`	Always set	Custom context passed between Hooks. More details.
`doc`	`object`	Always set	The Document that was deleted.
`id`	`string \| number`	Always set	The ID of the Document that was deleted.
`req`	`FrogBotRequest`	Always set	The request, with the signed-in `user` and `req.frogbot`. For Local API operations without a `req`, FrogBot creates one.

afterOperation

The afterOperation hook can be used to modify the result of operations or execute side-effects that run after an operation has completed.

import type { CollectionAfterOperationHook } from 'frogbot'

const afterOperationHook: CollectionAfterOperationHook = async ({ result }) => {
  return result
}

The following arguments are provided to the afterOperation hook:

Option	Type	Default	Description
`args`	`object`	Always set	The arguments passed into the operation.
`collection`	`SanitizedCollectionConfig`	Always set	The Collection in which this Hook is running against.
`req`	`FrogBotRequest`	Always set	The request, with the signed-in `user` and `req.frogbot`. For Local API operations without a `req`, FrogBot creates one.
`operation`	`string`	Always set	The name of the operation that this hook is running within, with the same values as `beforeOperation`.
`result`	`unknown`	Always set	The result of the operation, before modifications. Return a value to replace it.
`overrideAccess`	`boolean`	—	Whether the operation skips access control.

afterError

The afterError Hook is triggered when an error occurs in the FrogBot application. This can be useful for logging errors to a third-party service, sending an email to the development team, logging the error to Sentry or DataDog, etc. The output can be used to transform the result object / status code.

import type { CollectionAfterErrorHook } from 'frogbot';

const afterErrorHook: CollectionAfterErrorHook = async ({
  error,
  req,
  collection,
}) => {...}

The following arguments are provided to the afterError Hook:

Option	Type	Default	Description
`error`	`Error`	Always set	The error that occurred.
`context`	`RequestContext`	Always set	Custom context passed between Hooks. More details.
`graphqlResult`	`GraphQLFormattedError`	—	The GraphQL result object, available if the hook is executed within a GraphQL context.
`req`	`FrogBotRequest`	Always set	The `FrogBotRequest` object that extends Web Request. Contains currently authenticated `user` and the Local API instance `frogbot`.
`collection`	`SanitizedCollectionConfig`	Always set	The Collection in which this Hook is running against.
`result`	`ErrorResult`	—	The formatted error result object, available if the hook is executed from a REST context.

beforeLogin

For Auth-enabled Collections, this hook runs during login operations where a user with the provided credentials exist, but before a token is generated and added to the response. You can optionally modify the user that is returned, or throw an error in order to deny the login operation.

import type { CollectionBeforeLoginHook } from 'frogbot'

const beforeLoginHook: CollectionBeforeLoginHook = async ({ user }) => {
  return user
}

The following arguments are provided to the beforeLogin hook:

Option	Type	Default	Description
`collection`	`SanitizedCollectionConfig`	Always set	The Collection in which this Hook is running against.
`context`	`RequestContext`	Always set	Custom context passed between Hooks. More details.
`req`	`FrogBotRequest`	Always set	The request, with the signed-in `user` and `req.frogbot`. For Local API operations without a `req`, FrogBot creates one.
`user`	`object`	Always set	The user being logged in.

afterLogin

For Auth-enabled Collections, this hook runs after successful login operations. You can optionally modify the user that is returned.

import type { CollectionAfterLoginHook } from 'frogbot';

const afterLoginHook: CollectionAfterLoginHook = async ({
  user,
  token,
}) => {...}

The following arguments are provided to the afterLogin hook:

Option	Type	Default	Description
`collection`	`SanitizedCollectionConfig`	Always set	The Collection in which this Hook is running against.
`context`	`RequestContext`	Always set	Custom context passed between Hooks. More details.
`req`	`FrogBotRequest`	Always set	The request, with the signed-in `user` and `req.frogbot`. For Local API operations without a `req`, FrogBot creates one.
`token`	`string`	Always set	The token generated for the user.
`user`	`object`	Always set	The user being logged in.

afterLogout

For Auth-enabled Collections, this hook runs after logout operations.

import type { CollectionAfterLogoutHook } from 'frogbot';

const afterLogoutHook: CollectionAfterLogoutHook = async ({
  req,
}) => {...}

The following arguments are provided to the afterLogout hook:

Option	Type	Default	Description
`collection`	`SanitizedCollectionConfig`	Always set	The Collection in which this Hook is running against.
`context`	`RequestContext`	Always set	Custom context passed between Hooks. More details.
`req`	`FrogBotRequest`	Always set	The request, with the signed-in `user` and `req.frogbot`. For Local API operations without a `req`, FrogBot creates one.

afterMe

For Auth-enabled Collections, this hook runs after me operations.

import type { CollectionAfterMeHook } from 'frogbot';

const afterMeHook: CollectionAfterMeHook = async ({
  req,
  response,
}) => {...}

The following arguments are provided to the afterMe hook:

Option	Type	Default	Description
`collection`	`SanitizedCollectionConfig`	Always set	The Collection in which this Hook is running against.
`context`	`RequestContext`	Always set	Custom context passed between Hooks. More details.
`req`	`FrogBotRequest`	Always set	The request, with the signed-in `user` and `req.frogbot`. For Local API operations without a `req`, FrogBot creates one.
`response`	`unknown`	Always set	The response to return.

afterRefresh

For Auth-enabled Collections, this hook runs after refresh operations.

import type { CollectionAfterRefreshHook } from 'frogbot';

const afterRefreshHook: CollectionAfterRefreshHook = async ({
  token,
}) => {...}

The following arguments are provided to the afterRefresh hook:

Option	Type	Default	Description
`collection`	`SanitizedCollectionConfig`	Always set	The Collection in which this Hook is running against.
`context`	`RequestContext`	Always set	Custom context passed between Hooks. More details.
`exp`	`number`	Always set	The expiration time of the token, as a Unix timestamp in seconds.
`req`	`FrogBotRequest`	Always set	The request, with the signed-in `user` and `req.frogbot`. For Local API operations without a `req`, FrogBot creates one.
`token`	`string`	Always set	The newly refreshed user token.

afterForgotPassword

For Auth-enabled Collections, this hook runs after successful forgotPassword operations. Returned values are discarded.

import type { CollectionAfterForgotPasswordHook } from 'frogbot'

const afterForgotPasswordHook: CollectionAfterForgotPasswordHook = async ({
  args,
  context,
  collection,
}) => {...}

The following arguments are provided to the afterForgotPassword hook:

Option	Type	Default	Description
`args`	`object`	—	The arguments passed into the operation.
`collection`	`SanitizedCollectionConfig`	Always set	The Collection in which this Hook is running against.
`context`	`RequestContext`	Always set	Custom context passed between Hooks. More details.

refresh

For Auth-enabled Collections, this hook allows you to optionally replace the default behavior of the refresh operation with your own. If you optionally return a value from your hook, the operation will not perform its own logic and continue.

import type { CollectionRefreshHook } from 'frogbot'

const myRefreshHook: CollectionRefreshHook = async ({
  args,
  user,
}) => {...}

The following arguments are provided to the refresh hook:

Option	Type	Default	Description
`args`	`object`	Always set	The arguments passed into the operation, including `req`.
`user`	`object`	Always set	The user whose token is being refreshed.

me

For Auth-enabled Collections, this hook allows you to optionally replace the default behavior of the me operation with your own. If you optionally return a value from your hook, the operation will not perform its own logic and continue.

import type { CollectionMeHook } from 'frogbot'

const meHook: CollectionMeHook = async ({
  args,
  user,
}) => {...}

The following arguments are provided to the me hook:

Option	Type	Default	Description
`args`	`object`	Always set	The arguments passed into the operation, including `req`.
`user`	`object`	Always set	The signed-in user.

TypeScript

FrogBot exports a type for each Collection hook which can be accessed as follows:

import type {
  CollectionBeforeOperationHook,
  CollectionBeforeValidateHook,
  CollectionBeforeChangeHook,
  CollectionAfterChangeHook,
  CollectionAfterReadHook,
  CollectionBeforeReadHook,
  CollectionBeforeDeleteHook,
  CollectionAfterDeleteHook,
  CollectionBeforeLoginHook,
  CollectionAfterLoginHook,
  CollectionAfterLogoutHook,
  CollectionAfterRefreshHook,
  CollectionAfterMeHook,
  CollectionAfterForgotPasswordHook,
  CollectionRefreshHook,
  CollectionMeHook,
} from 'frogbot'

You can also pass a generic type to each hook for strongly-typed doc, previousDoc, and data properties:

import type { CollectionAfterChangeHook } from 'frogbot'
import type { Post } from '@/frogbot-types'

const afterChangeHook: CollectionAfterChangeHook<Post> = async ({
  doc, // Typed as Post
  previousDoc, // Typed as Post
}) => {
  return doc
}

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Config Options

beforeOperation

beforeValidate

beforeChange

afterChange

beforeRead

afterRead

beforeDelete

afterDelete

afterOperation

afterError

beforeLogin

afterLogin

afterLogout

afterMe

afterRefresh

afterForgotPassword

refresh

me

TypeScript

​Config Options

​beforeOperation

​beforeValidate

​beforeChange

​afterChange

​beforeRead

​afterRead

​beforeDelete

​afterDelete

​afterOperation

​afterError

​beforeLogin

​afterLogin

​afterLogout

​afterMe

​afterRefresh

​afterForgotPassword

​refresh

​me

​TypeScript

Config Options

beforeOperation

beforeValidate

beforeChange

afterChange

beforeRead

afterRead

beforeDelete

afterDelete

afterOperation

afterError

beforeLogin

afterLogin

afterLogout

afterMe

afterRefresh

afterForgotPassword

refresh

me

TypeScript