Exit Hooks

Recipes for what happens when a user deletes their account: delete their files, cancel something at another provider, refuse the deletion, and why every hook must be safe to run twice.

Account deletion calls three kinds of extension points, all in apps/web/config/account-hooks.config.server.ts (yours to edit). Pick by when the work must happen:

You want toUseRunsCan stop the delete?
Refuse the delete with a reasonaccountPoliciesWhen the code is requested, on Delete, and each time the Profile page loads (for the dialog's blockers): keep it cheap and read-onlyYes
Do work while the user's rows still exist, or at a provideraccountDeleteStepsAfter the code, before the transactionYes (a denial)
Clean up after the account is gone (files, other systems)afterAccountDeleteIn the account.deleted-hooks jobNo: the job retries, then goes dead after its attempts and waits to be replayed (Running and Failures)

Organizations the user deletes with them run through your organization policies, steps and afterOrganizationDelete hooks too (Deleting an Organization).

Every Hook Must Be Idempotent

The account.deleted-hooks job runs your afterOrganizationDelete hooks for each deleted organization, then your afterAccountDelete hooks. If one throws, the job fails and the outbox runs the whole list again from the first hook. A step runs again if the delete is retried after a refusal. Write each one to be safe to run twice: delete by id (deleting nothing is success), check before you create, key external calls by the user's id.

An account hook gets the user's id only ({ id }): the row is gone; an organization hook gets { id, name }. A hook receives { signal } from the job too: pass it to every network or database call so a timed-out attempt stops instead of running beside its retry.

Recipe: Delete a User's Files

User-owned files in your storage go in an after-hook: the user's rows no longer exist, and the files are named by the user's id.

import type { AfterAccountDeleteHook } from '@kit/organizations/server';
export const afterAccountDelete: AfterAccountDeleteHook[] = [
async ({ id }, context) => {
// an upload kind with `owner: 'user'` is purged by the kit; this is for
// objects you wrote yourself, under a prefix named by the user's id
await deleteReports({ userId: id, signal: context?.signal }); // deleting nothing is success
},
];

If your files are an upload kind with owner: 'user', you need no hook: the kit purges them after the delete, like the avatar.

Recipe: Cancel an External Resource

Work that needs your rows (an id you stored for another provider) goes in a step, before the transaction, while they exist. A denial stops the delete and the user sees your message; the next try runs the step again.

import { allow, deny } from '@kit/policies';
import type { AccountDeleteStep } from '@kit/organizations/server';
export const accountDeleteSteps: AccountDeleteStep[] = [
{
id: 'app.cancel-crm-contact',
// shown in the dialog's warnings (a translation key), or omit
warning: async () => 'app.account.crmWarning',
run: async ({ userId }) => {
const failed = await removeCrmContact(userId); // idempotent: gone is fine
return failed
? deny({ code: 'CRM_DOWN', message: 'app.account.crmDown' })
: allow();
},
},
];

The kit's own step, ending the user's subscription in Stripe, runs first. A step may write; it must not assume it runs once.

Recipe: Refuse a Deletion

A policy decides from the database whether the user may delete now: a legal hold, an unpaid invoice, an open dispute.

import { allow, deny } from '@kit/policies';
import { createAccountPolicies, defineAccountPolicy } from '@kit/organizations/server';
export const accountPolicies = createAccountPolicies().registerPolicy(
defineAccountPolicy({
id: 'app.legal-hold',
stages: ['delete'],
evaluate: async ({ userId }) =>
(await isOnLegalHold(userId))
? deny({
code: 'LEGAL_HOLD',
message: 'app.account.legalHold',
remediation: 'app.account.contactLegal',
// a path in your app: the remediation becomes a link to it
remediationHref: '/support',
})
: allow(),
}),
);

The message is a translation key in your messages. The kit's own rules (a recent sign-in, the owner rule, the last admin, a live subscription with Stripe off) run first and can't be dropped (Authorization Policies).

Testing

Call the hook with an id and assert the end state; run the job end to end with runUntilIdle (Testing). For retry behaviour, make a hook throw once and assert that it ran twice and the email went out once (apps/web/config/__tests__/account-deletion.server.test.ts).


Back: Cleanup Overview →