TL;DR: Developers can now run any Gadget action as an async task, with zero setup or integration.

Run actions on your terms. Every Gadget app now comes with background actions built-in, so you can process operations the way it works best for your project. Also known as background jobs, queues, or tasks, these actions let you enqueue long-running or unreliable work to happen in the background with retries.

With background actions in Gadget, you’re able to balance reliability and performance for your end users without compromising on your own development experience. Enqueue an action, and Gadget’s auto-scaled queueing system will execute your action as soon as possible on the same serverless stack your app already uses. You can process millions of records, make rate-limited external API calls, or run slow business logic without worrying about requests failing and breaking the user experience. 

And all of this can be done with a single line of code. Wrap your existing action calls with <inline-code>api.enqueue<inline-code> to run them in the background and let us take care of the rest. You can forget about setting up Redis, provisioning workers, configuring AWS SQS or Google Cloud Tasks — just enqueue your tasks and watch them run. As a bonus, you can now monitor your Shopify webhooks, so you can see how your webhooks have failed.

What are background actions?

A background action is a unit of work (an action) enqueued to run at some point soon, instead of right away. Background actions are useful for long-running tasks that don't need to happen immediately but are still critical to complete. These actions are handled separately from the main execution flow of an application by running in the background, allowing requests from users to remain snappy, while still ensuring the primary application processes can run uninterrupted.

Normally, when a developer chooses to implement background jobs in a traditional development environment, there can be hours of work involved. You have to set up a queueing system that can scale to your needs, register workers, define your tasks, schedule them, and learn to work with a new API before you finally get to execute anything.

On top of all that, you need to set up monitoring tools to understand whether jobs are executing as expected, or you risk disappointing users when your features break. Logs, dashboards, and metrics all play a role in running and managing your background execution system. Since background jobs are such a critical part of complex projects, for a long time, the setup has been a necessary evil. And the complexity only gets worse as an application scales and the number of background jobs needed increases.

With Gadget, you get a built-in queue system and comprehensive monitoring tools out of the box. No setup, no configuration, no new API, no new constraints! You skip right to the fun part: actually writing your code.

How background actions work

To add a background action to your Gadget project, you define a normal action, and then enqueue it to run in the background. Actions are serverless JavaScript functions that run in your Gadget backend, with access to your database and the rest of Gadget's framework. Actions can be run in the foreground or in the background when they have an API trigger.

For example, let's say we have a global action defined in <inline-code>api/actions/sendAnEmail.ts<inline-code>:

You can run this action in the foreground by making an API call (from either your backend or frontend):

And you can run this action in the background by enqueuing the action with parameters if needed.

That’s it – no complex integrations or tedious setup required. Once you've enqueued your action, Gadget will run it as soon as it can in your serverless hosting environment. You can set a maximum number of retries, and view the status and outcome of a background action in the Queues section within your Gadget editor.

When should you run background actions?

Most of the work our applications do will deliver immediate results to a user, but sometimes we’re confronted with important or large tasks that need to be completed, but aren’t essential to the user experience. Think about a huge CSV import for example – because there are a lot of records, the process can be slow. It doesn’t make sense to show the user a 10 minute spinner, if the task can be processed in the background. Gadget’s background actions, just like background jobs or asynchronous tasks, can be used to keep your app responsive and snappy.

There are a few reasons you may want to use background actions.

Performance optimization

Despite the complexity of a task, users still want to see results, so maintaining an immediate feedback loop for application responses is essential. With background actions, you can ensure that the user interface remains responsive, even while your application is executing heavy-duty tasks. By offloading time-consuming tasks to the background, your project is able to respond to user requests more quickly. This reduction in wait time for the end-user is crucial for tasks that require significant processing time, such as sending batch emails, generating reports, or handling large data operations.

As applications scale, and the volume of tasks increases, that can potentially slow down your processing speeds. Background actions let you handle a growing workload by distributing tasks across different workers or servers. This distribution helps in managing load spikes and ensures that your Gadget project remains responsive.

Processing time-consuming and error-prone operations

For tasks that take a considerable amount of time to complete, such as generating reports, processing images, or performing complex calculations, background actions allow these tasks to be offloaded from the main application flow. 

Handling external API calls

When interacting with external services or APIs, network latency and rate limiting can introduce delays. Background actions are ideal for managing these calls, especially when the outcome does not need to be immediately presented to the user. They also allow for efficient retry mechanisms in case of failures.

Scheduled tasks

For tasks that need to run at specific intervals, such as a data sync, email notifications, or cleanup operations, background actions can be scheduled to run independently of user interactions, ensuring that these operations do not impact the overall performance of the application.

Batch processing

Performing operations on large datasets, like batch updates, exports, or imports, can be resource-intensive. By using background actions, these operations can be processed in smaller, manageable chunks without blocking the main functionality within your application.

Background actions are available on all new Gadget projects, so you can start using them for free as of today. To use background actions on an existing project, you will need to upgrade to Gadget framework v1.0. If you want to learn more about working with background actions, you can read through our docs for details.

If you have any questions or need help getting started, we’re always here to help in our developer Discord.