Nitro Tasks API

[pi0]

Nitro tasks allow on-off operations in runtime.

Docs: https://nitro.unjs.io/guide/tasks

### Tasks
- [x] Initial Implementation (#1929)
- [x] Write documentation section (PR welcome!)
- [x] Stabilize API / return values
- [x] Integrate with Cron Tasks / Background Jobs
- [ ] Ability to run tasks using CLI against production build
- [ ] Task hooks (on dev start, production start and production build)
- [ ] Ability to schedule one time run of a task for the future
- [ ] Allow optionally allow running multiple instances of task
- [ ] https://github.com/unjs/nitro/issues/2633

### Tasks

[Aareksio]

Tasks should probably be async, currently the run method expects synchronous code and is not awaited.

[manniL]

@Aareksio check #2021 ☺️

[Rigo-m]

If I use a nitro task in, let's say, Netlify will it leverage netlify background functions?

[cosbgn]

I'm also interested on this. I would like to have for example my normal code on vercel-edge but run tasks on vercel lambda (5min timeout vs 25 seconds)

[imcm7]

How to disable it, because i use dir tasks for other stuff?

[brendonmatos]

It is planned to support running these tasks from cli without running the server?

[pi0]

Nitro already has a CLI preset too! However it is tricky to tell now when we can do support it this way now.

[robin-dongbin]

Any plan for support seconds scheduling?

[pi0]

@robin-dongbin You mean this https://nitro.unjs.io/guide/tasks#scheduled-tasks or something different? (like a pattern for <1 minute schedule?)

[robin-dongbin]

@robin-dongbin You mean(意味着) this nitro.unjs.io/guide/tasks#scheduled-tasks or something different? (like a pattern(模式) for <1 minute(分钟) schedule?)

Yes, that's what I want. Is it possible? I know that cron do not support that, but Laravel has support this last year.

[go4cas]

@pi0 ... I have just tested the experimental scheduled task feature. It works really well! Thanks!

Just one question: would it be possible to have a config setting to execute a scheduled task immediately after the cron is scheduled? Example: a task running every 10 minutes: executes once the server starts, and then every 10 minutes after that? I saw in the croner docs that there is a trigger method, but not sure how it would fit into the nitro tasks?

[pi0]

@go4cas Maybe use a Nitro plugin to triger them on startup? (also init: / startup: tasks are planned to be supported to have similar effect in the future). Also you can execute a task from another.

@robin-dongbin I also wonder if you need to trigger something this frequently, maybe a setInterval inside nitro plugins to run task with runTask might be simpler method with giving full control on executation?

[JCtapuk]

@go4cas Maybe use a Nitro plugin to triger them on startup? (also init: / startup: tasks are planned to be supported to have similar effect in the future). Also you can execute a task from another.

@robin-dongbin I also wonder if you need to trigger something this frequently, maybe a setInterval inside nitro plugins to run task with runTask might be simpler method with giving full control on executation?

But won’t there be conflicts if a node in a cluster with 8 processes and all 8 processes will cause a task, but this behavior should not happen? It turns out you need to find someone who has a free worker and give him a task from the master?

[pi0]

For time being, scheduled tasks are not supported in cluster mode the exactly meet this requirement (share a safe lock among them) and it is doable.

Regardless inside your interval you can call runTask() in single node, it currently guarantees only it is running once and when we support cluster, it would be safe too.

[brendonmatos]

I apologize if this isn't the correct forum. But how is supposed to run those tasks in Nuxt project from CLI? Nuxt CLI will be implemented to invoke those tasks from the URL or we should run directly from nitro cli?

[pi0]

Yes.

[passionate-bram]

With async tasks, and enforcing task payloads to be serializable early on it will be possible in the future to dispatch tasks to queues. Shamelessly taking the concept from Laravel: https://laravel.com/docs/10.x/queues

The nice thing about that way of working is that when queues are configurable (e.g. redis, some AWS service, etc.) then the dispatch mechanic becomes really usefull for dispatching work to different parts of your architecture.

[pi0]

payload should be serializable indeed in preparation for future ideas like queues. and it is by design separated from context that is non seriazable for other stuff. PR welcome to clarify in the docs.

[ivanjeremic]

@pi0 A use case would be a platform that allows users to add / remove services that in the background add / remove tasks. I have not really good example in mind but maybe something like Hootsuite that allows its users to schedule posts for a specific time for a social media platform.

[manniL]

@ivanjeremic couldn't you run a job every X minutes that checks if some posts are queued up, then processing them if so? 🤔

[ivanjeremic]

No. The Hootsuite/Posts example was just an example there are thousends other use cases.

[ivanjeremic]

@manniL I wanted to say I'm new to tasks/cron and maybe the way I think about this problem is wrong, I think you are right and the way you described it is a simpler way of doing what I want.

[pi0]

Thanks for explaining your idea @ivanjeremic. I think in the future something like this would unblock this and i have added two tasks to tracker.

runTask('useTask', {
  scheduled: 5 * 60, /* 5 minutes */
  multiple: true,
  payload: {
    userId: 123
  }
})

(above snippet is just an example to show the idea)

[ivanjeremic]

Thanks for explaining your idea @ivanjeremic. I think in the future something like this would unblock this and i have added two tasks to tracker.

runTask('useTask', {

  scheduled: 5 * 60, /* 5 minutes */

  multiple: true,

  payload: {

    userId: 123

  }

})

(above snippet is just an example to show the idea)

Exactly how I imagined it👍🏻

[iBobik]

It would be handy to disable cron tasks in dev server by default, but keep ability to run it manually.

It is annoying when I need to debug something else and see log full of unrelated periodic tasks. It also unnecessary eats battery of laptop.

[casualmatt]

It's very nice how the tasks show up in nuxt devtools; I tried to use h3 utility to send a stream back but didn't succeed because they need the event; this could be an excellent tool to keep track of the task activity.

[malgamves]

New to this so curious if it normal that when i setup a task in Nuxt to return something and use the cron scheduler in my Nuxt config, my tasks run but i don't get the return object i'm expecting.

When i run the task programmatically, say through an api route in Nuxt, i get the return object.

Edit.

Turns out i was printing out the return object programatically.
It would be nice to have status modes logged (success, failure) - this would tie in really well with the queues idea.
Might be interesting use cases around error handing for batching and other operations.

[jsonleex]

Thanks for the awesome feature! 🫰

Is there any way to create a new task within a task, or can tasks be created during runtime?

[AwesomePeregrineFalcon]

Do you want to add the ability to run tasks from CLI? Like

node .output/server/index.mjs db:migrate

or

node .output/server/index.mjs task run db:migrate

I really liked Nitro but this feature is kinda deal-breaker for me. As I understand, there is no way right now to make such commands because Nitro makes its own entry-point to the app, and I can't add operations before it like I would be able if I used something like express.js, so I can't add CLI

[pi0]

@AwesomePeregrineFalcon it is in the plan yes to allow CLI interaction with production build. In the meantime you can expose a (protected) API endpoint.

[juretopolak]

The only thing that i need to figure out is how to get cloudflare d1 working in the tasks context

@TMBL-DEV have you figured this out? 🙂

[AwesomePeregrineFalcon]

it is in the plan yes to allow CLI interaction with production build. In the meantime you can expose a (protected) API endpoint.

@pi0, I figured out how to make CLI. I made the custom preset. Just used Commander.js library in server/preset/entry.ts and made the listening start in a subcommand, so I start the server with

node .output/server/index.mjs server listen

and run migrations with

node .output/server/index.mjs db migrate

But now I have to build the project to use CLI 😞. Anyway, it works now... And I liked everything else in Nitro.js! Is there a reason why there is no possibility to run a custom preset in dev mode? Something like:

yarn dev server listen

[dalbodeule]

Wouldn't it be possible to bind specific tasks to the Task API? For example, it might be a good idea to apply cloudflare worker's email handler or queue handler.

While looking at related issues and PRs, I thought it was a good idea and suggested it.

[luke-z]

I just came across the Tasks API and was wondering if eventually it could replace a package like bullmq for simple jobs and a worker type of setup.

Allow optionally allow running multiple instances of task

Seems to get close to this kind of feature.

Or am I somehow misunderstanding it :)

[kyng-cytro]

Hey, does the cron Synatx have support for time zones? I know Croner does.

[provok-me]

If I use a nitro task in, let's say, Netlify will it leverage netlify background functions?

@pi0
A Nitro task has only one running instance, but Netlify background functions can handle multiple instances at the same time (as I understand it in there docs).

Is there another way to use Netlify background functions with Nitro to handle multiple instances of a background function?

[StepanMynarik]

Using Nuxt 3.

Tried building an endpoint to get scheduled jobs using 'scheduledJobs' variable imported from "cron" package directly, see here: https://croner.56k.guru/usage/examples/#naming-jobs
My intention was to build a UI that shows the scheduled jobs, ideally even which ones are currently running with which payload etc.

The 'scheduledJobs' variable however returns an empty array always.

Is there a way to do this? To monitor scheduled and running jobs?

[luc122c]

Hi @pi0, I'm wondering how scheduled tasks are handled in a serverless context? For example, I am currently using the Firebase preset which uses a Firebase Function as the 'server'. Since the server is not long-lived, would scheduled tasks execute each time the service is called, or are they not included in unsupported presets?

[gbyesiltas]

hey, is it currently possible to create a nuxt application with tasks and get it to work with cloudflare triggers? (as it's deployed as a pages application I couldn't get it to work)

update: i got it to work after deploying the nuxt app with the cloudflare_module preset here which deploys it as a workers application

[carlos-duran]

Hello, I was trying to run nitro task run hi in a Nuxt 3 app but it looks like the .nitro folder is expected. We have .nuxt folder.

Btw, Thank you for a great API!

[TMBL-DEV]

@carlos-duran i had the same issue i have an open pull request at the moment that should fix it

#2635

btw you can edit your buildDir in the nuxt config

// https://nuxt.com/docs/api/configuration/nuxt-config
export default defineNuxtConfig({
  compatibilityDate: '2024-04-03',
  devtools: { enabled: true },
  buildDir: '.nitro',
  nitro: {
    buildDir: '.nitro', 
    experimental: {
      tasks: true,
    }
  }
})

and replace .nuxt in the tsconfig file with .nitro

[aligzl]

hey, is it currently possible to create a nuxt application with tasks and get it to work with cloudflare triggers? (as it's deployed as a pages application I couldn't get it to work)

update: i got it to work after deploying the nuxt app with the cloudflare_module preset here which deploys it as a workers application

Can you please give an example how you did it?
Thanks

[gbyesiltas]

Can you please give an example how you did it?
Thanks

@aligzl hey, I pretty much exactly followed the docs for the cloudflare_preset module which I believe builds/deploys the app as a workers application and not as a pages application. Nitro tasks started working for me after that

[aligzl]

hmm, i am using nuxt hub, i guess i will mess it up if i touch it :)

[zacwebb]

hmm, i am using nuxt hub, i guess i will mess it up if i touch it :)

I'm in the same boat with NuxtHub. With the new Cloudflare worker updates, support for this will be coming soon to NuxtHub I believe (cc @atinux 👀)