50.tasks.md

icon	codicon:run-all

Tasks

Nitro tasks allow on-off operations in runtime.

::warning Nitro v3 Alpha docs are a work in progress — expect updates, rough edges, and occasional inaccuracies. ::

Opt-in to the experimental feature

Important

Tasks support is currently experimental. See nitrojs/nitro#1974 for the relevant discussion.

In order to use the tasks API you need to enable experimental feature flag.

import { defineNitroConfig } from "nitro/config";

export default defineNitroConfig({
  experimental: {
    tasks: true
  }
})

Define tasks

Tasks can be defined in tasks/[name].ts files.

Nested directories are supported. The task name will be joined with :. (Example: tasks/db/migrate.tstask name will be db:migrate)

Example:

export default defineTask({
  meta: {
    name: "db:migrate",
    description: "Run database migrations",
  },
  run({ payload, context }) {
    console.log("Running DB migration task...");
    return { result: "Success" };
  },
});

Scheduled tasks

You can define scheduled tasks using Nitro configuration to automatically run after each period of time.

import { defineNitroConfig } from "nitro/config";

export default defineNitroConfig({
  scheduledTasks: {
    // Run `cms:update` task every minute
    '* * * * *': ['cms:update']
  }
})

Tip

You can use crontab.guru to easily generate and understand cron tab patterns.

Platform support

• dev, node-server, bun and deno-server presets are supported with croner engine.
• cloudflare_module preset has native integration with Cron Triggers. Make sure to configure wrangler to use the same patterns you define in scheduledTasks to be matched.
• vercel preset has native integration with Vercel Cron Jobs. Nitro automatically generates the cron job configuration at build time — no manual vercel.json setup required.
• More presets (with native primitives support) are planned to be supported!

Programmatically run tasks

To manually run tasks, you can use runTask(name, { payload? }) utility.

Example:

export default eventHandler(async (event) => {
  // IMPORTANT: Authenticate user and validate payload!
  const payload = { ...getQuery(event) };
  const { result } = await runTask("db:migrate", { payload });

  return { result };
});

Run tasks with dev server

Nitro's built-in dev server exposes tasks to be easily executed without programmatic usage.

Using API routes

/_nitro/tasks

This endpoint returns a list of available task names and their meta.

// [GET] /_nitro/tasks
{
  "tasks": {
    "db:migrate": {
      "description": "Run database migrations"
    },
     "cms:update": {
      "description": "Update CMS content"
    }
  },
  "scheduledTasks": [
    {
      "cron": "* * * * *",
      "tasks": [
        "cms:update"
      ]
    }
  ]
}

/_nitro/tasks/:name

This endpoint executes a task. You can provide a payload using both query parameters and body JSON payload. The payload sent in the JSON body payload must be under the "payload" property.

::code-group

export default defineTask({
  meta: {
    name: "echo:payload",
    description: "Returns the provided payload",
  },
  run({ payload, context }) {
    console.log("Running echo task...");
    return { result: payload };
  },
});

// [GET] /_nitro/tasks/echo:payload?field=value&array=1&array=2
{
  "field": "value",
  "array": ["1", "2"]
}

/**
 * [POST] /_nitro/tasks/echo:payload?field=value
 * body: {
 *   "payload": {
 *     "answer": 42,
 *     "nested": {
 *       "value": true
 *     }
 *   }
 * }
 */
{
  "field": "value",
  "answer": 42,
  "nested": {
    "value": true
  }
}

::

Note

The JSON payload included in the body will overwrite the keys present in the query params.

Using CLI

Important

It is only possible to run these commands while the dev server is running. You should run them in a second terminal.

List tasks

nitro task list

Run a task

nitro task run db:migrate --payload "{}"

Notes

Concurrency

Each task can have one running instance. Calling a task of same name multiple times in parallel, results in calling it once and all callers will get the same return value.

Note

Nitro tasks can be running multiple times and in parallel.