---
title: "Tasks"
description: "Scheduled and manual tasks with Nitro's defineTask, run by wervt."
canonical_url: "https://docs.dev.lightdrop.cloud/guides/tasks"
---
# Tasks

> Scheduled and manual tasks with Nitro's defineTask, run by wervt.

Periodic work, like sweeping stale rows, renewing webhooks or syncing a calendar, goes into
tasks. Write them the Nitro way; wervt runs them on schedule.

```ts [server/tasks/presence/sweep.ts]
import { defineTask, useDb } from '@wervt/nuxt/server'
import { lt } from 'drizzle-orm'
import { presence } from '../../db/schema'

export default defineTask({
  meta: { description: 'Remove presence older than 5 minutes' },
  async run({ payload }) {
    const cutoff = new Date(Date.now() - 5 * 60_000)
    await useDb().delete(presence).where(lt(presence.seenAt, cutoff))
    return { result: 'ok' }
  },
})
```

The file path is the task's name: `server/tasks/presence/sweep.ts` is `presence:sweep`. Schedule it
in `nuxt.config.ts` with standard cron expressions:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@wervt/nuxt'],
  nitro: {
    scheduledTasks: {
      '*/5 * * * *': ['presence:sweep'],
      '0 4 * * *': ['eventsub:renew'],
    },
  },
  // Optional: the schedules' time zone. UTC by default.
  wervt: { timezone: 'Europe/Berlin' },
})
```

Schedules deploy and roll back with the code. `nuxt dev` runs them locally with Nitro's own
scheduler.

## How wervt runs them

Isolates stop when they're idle, so an app can't keep a clock itself. The control plane does: on
every deploy, activation or rollback it loads the app's schedules, and when one is due it calls the
task in the app's isolate through the runtime.

- **Limits:** a run has the limits of a request: 5 minutes and limited CPU time. Keep tasks short;
split big jobs into batches across runs.
- **No overlap:** if a task is still running when it's due again, that run is skipped.
- **No catch-up:** runs that were due while wervt was down are skipped, not made up later. Write tasks so
the next run does what a missed one would have.
- **At most once a minute.** Cron expressions have minute precision.

## Running and watching tasks

The app's **Tasks** page in the dashboard lists its tasks with their schedules and next runs, the
last result, and a **Run now** button. Tasks without a schedule can be run there too, for
one-off jobs like a backfill.

```bash
wervt tasks my-app                                   # tasks, schedules, next runs
wervt tasks my-app --run presence:sweep              # run now and wait for the result
wervt tasks my-app --run import:users --payload '{"since":"2026-01-01"}'
wervt logs my-app 'type:=Task' --since 1d            # every run: status, duration, errors
```

A manual run gets its `--payload` as `payload`; scheduled runs get `{ scheduledTime }`.

## Merged accounts

Some people sign up twice, for example once with Discord and once with Google under another
address. An admin merges the two (`wervt accounts <from> --into <into>`): logins, app ownership
and access move to `into`, and `from` is deleted. Data in your app's own tables only moves if the
app says how, with a task named `wervt:account-merged`:

```ts [server/tasks/wervt/account-merged.ts]
import { defineTask, useDb, type AccountMergedPayload } from '@wervt/nuxt/server'
import { eq } from 'drizzle-orm'
import { players } from '../../db/schema'

export default defineTask<unknown, AccountMergedPayload>({
  meta: { description: 'Move a merged account\'s rows to the account it was merged into' },
  async run({ payload: { from, into } }) {
    await useDb().update(players).set({ userId: into.id }).where(eq(players.userId, from.id))
    return { result: 'ok' }
  },
})
```

wervt runs it in every app that has it, right after the merge. Where both accounts have a row
that must be unique (a membership in the same room), keep one. A failed run doesn't undo the
merge: fix the task and run it again with the payload the CLI prints, so write it to be
idempotent. Key users by `user.id` rather than email: the id is what the payload names, and
addresses change.

## Changed addresses

People change their address on their account page, with a code to the old address and one to the
new one. If the old mailbox is gone, an admin can do it for them
(`wervt accounts <from> --change-email <into>`). The account keeps its `user.id`, and its app
ownership, memberships, list entries, invites and limits move to the new address. No task runs:
apps that key users by id have nothing to move. `useWervtUser()` has the new address right away
on the device where it was changed, and on other devices within 12 hours, when their session
renews.

## Seeding

A task named `db:seed` (`server/tasks/db/seed.ts`) fills a new database with example data:
`nuxt dev` runs it once on a new local database, and it never runs on a schedule or on deploy. See
[Seeding](https://docs.dev.lightdrop.cloud/guides/database#seeding).


## Sitemap

See the full [sitemap](https://docs.dev.lightdrop.cloud/sitemap.md) for all pages.
