> ## Documentation Index
> Fetch the complete documentation index at: https://www.chapterjs.org/llms.txt
> Use this file to discover all available pages before exploring further.

# task()

> Everything a task file declares: its schedule, its timezone, and what the run function receives

`task()` declares a task, from any file of `src/`, and the name of its export is the name of the task. It takes one object, `TaskConfig`.

```ts src/tasks/cleanup.ts theme={"theme":{"light":"github-light","dark":"vesper"}}
import { task } from 'chapterjs';

export default task({
  every: '10m',
  async run({ guilds }) {
    console.log(`Watching ${guilds.size} servers`);
  },
});
```

> [!NOTE]
>
> How to write a task, and what happens when a run takes long or fails, is in the [guide](https://www.chapterjs.org/tasks.md). This page lists what exists.

## task()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
task(config: TaskConfig): TaskDeclaration
```

Declares a task: something the bot does by itself. Export the result from any file of `src/`: the name of the export is the name of the task.

### TaskDeclaration

What `task()` returns: a declaration the framework finds in the exports of a file.

**config** `unknown`

What the file gave to `task()`, not checked yet.

## TaskConfig

What a task file gives to `task()`: when it runs, and what it does. It is an `EveryTaskConfig` or a `CronTaskConfig`: one of `every` and `cron`, never both.

**run** `(context: TaskContext) =\> unknown` *required*

What the task does.

**onStart** `boolean`

Also run once as soon as the bot is connected, without waiting for the first time of the schedule.

### EveryTaskConfig

A task that runs every so often.

**every** `string` *required*

How often the task runs: a number and a unit, `s`, `m`, `h` or `d`, like `'30s'`, `'10m'`, `'2h'`, `'1d'` or `'1h30m'`. Once per second at most. Counted from when the bot connects.

### CronTaskConfig

A task that runs at given times.

**cron** `string` *required*

When the task runs, as a cron expression: minute, hour, day of month, month and day of week, like `'0 9 * * 1-5'` (9:00 on weekdays). `*`, lists (`1,15`), ranges (`1-5`), steps (`*/15`) and names (`mon`, `jan`) work.

**timezone** `string`

The timezone the cron follows, like `'Europe/Paris'`. The clock of the machine by default.

When both the day of month and the day of week are given, the task runs on the days that match either, as cron does.

## TaskContext

What `run` receives: the bot, as the `ready` event gives it, and the time.

**user** `User` *required*

The bot itself.

**guilds** `ReadonlyMap\<Snowflake, Guild\>` *required*

The servers the bot is in.

**now** `Date` *required*

When this run was due.

A task also receives `t`, in the default language, when the project has a language: see [`TranslationContext`](https://www.chapterjs.org/reference/messages#translationcontext).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.