icon |
---|
codicon:run-all |
Nitro tasks allow on-off operations in runtime.
Important
Tasks support is currently experimental. See unjs/nitro#1974 for the relevant discussion.
In order to tasks API you need to enable experimental feature flag.
::code-group
export default defineNitroConfig({
experimental: {
tasks: true
}
})
export default defineNuxtConfig({
nitro: {
experimental: {
tasks: true
}
}
})
::
Tasks can be defined in tasks/[name].ts
files.
Nested directories are supported. The task name will be joined with :
. (Example: tasks/db/migrate.ts
task 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 "Success";
},
});
Note
Use server/tasks/db/migrate.ts
for Nuxt.
You can define scheduled tasks using Nitro configuration to automatically run after each period of time.
::code-group
export default defineNitroConfig({
scheduledTasks: {
// Run `cms:update` task every minute
'* * * * *': ['cms:update']
}
})
export default defineNuxtConfig({
nitro: {
scheduledTasks: {
// Run `cms:update` task every minute
'* * * * *': ['cms:update']
}
}
})
::
Tip
You can use crontab.guru to easily generate and understand cron tab patterns.
dev
,node-server
,bun
anddeno-server
presets are supported with croner engine.cloudflare_module
preset have native integraton with Cron Triggers. Make sure to configure wrangler to use exactly same patterns you define inscheduledTasks
to be matched.- More presets (with native primitives support) are planned to be supported!
To manually run tasks, you can use runTask(name, { payload? })
utility.
Example:
// api/migrate.ts
export default eventHandler(async (event) => {
// IMPORTANT: Authenticate user and validate payload!
const payload = { ...getQuery(event) };
const { result } = await runTask("db:migrate", { payload });
return { result };
});
Nitro's built-in dev server exposes tasks to be easily executed without programmatic usage.
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"
]
}
]
}
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 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.
Important
It is only possible to run these commands while the dev server is running. You should run them in a second terminal.
nitro task list
nitro task run db:migrate --payload "{}"
Each task can have one running instance. Calling a task of same name multiple times in parallel, results to calling it once and all callers will get the same return value.
Note
Nitro tasks can be running multiple times and in parallel.