Get started with Async Workloads

This page will help you get started with the Async Workloads extension. It describes how to enable the extension, write basic workloads, and send events to them.

Key concepts

The Async Workloads extension turns Netlify serverless functions into durable, event-driven workloads. When you define workloads, you create serverless functions. Given this, the capabilities and limitations for serverless functions also apply to workloads. Any exceptions will be explicitly noted.

Learn more about serverless functions.

An Async Workload function is similar to a background function but is durable, event-driven, and offers more enhanced capabilities. The function runs asynchronously, so it will not return a Response object. Instead, the client can invoke the function by sending a matching event and the workload function can run its logic and persist any state it needs.

Setup

To get started, install the Async Workloads extension for your team. After you install the extension, all sites on your team will be able to build Async Workloads functions.

For teams on the Starter plan, you need to configure the extension with an Async Workloads API key. In the Netlify UI, navigate to Project configuration > Build & Deploy > Async Workloads for the site you want to configure. Select Create a new API key to input and save the new API key. For customers on all other plans, this step is optional as an API key is automatically generated for you at the team level upon installing the extension.

Add the @netlify/async-workloads module to your project. This will provide the functionality and types for those using TypeScript.

npm

npm

npm install @netlify/async-workloads

pnpm

pnpm

pnpm add @netlify/async-workloads

yarn

yarn

yarn add @netlify/async-workloads

Write an Async Workload function

Start by adding a serverless function to your project by creating the file in your functions directory.

A function file must be written using the JavaScript modules syntax and have a default export with a asyncWorkloadFn wrapped handler.

TypeScript

TypeScript

import { asyncWorkloadFn, AsyncWorkloadEvent, AsyncWorkloadConfig } from "@netlify/async-workloads";

export default asyncWorkloadFn((event: AsyncWorkloadEvent) => {

  console.log('Hello, Async Workloads!');

});

export const asyncWorkloadConfig: AsyncWorkloadConfig = {
  events: ['say-hello']
};

JavaScript

JavaScript

import { asyncWorkloadFn } from "@netlify/async-workloads";

export default asyncWorkloadFn((event) => {

  console.log('Hello, Async Workloads!');

});

export const asyncWorkloadConfig = {
  events: ['say-hello']
};

This workload will be called when the "say-hello" event is sent by a client. Once sent, this workload will run and log the message.

Send your first event

Async Workloads provides a client library called AsyncWorkloadsClient that can be used to send events.

The basic flow is to instantiate the client and then send the message.

const client = new AsyncWorkloadsClient();
// optionally send data
await client.send('EVENT_NAME', {data: {}});

Typically, Async Workload functions are triggered by other serverless endpoints that respond to user actions on a website. When this occurs, the client is instantiated and used within that serverless endpoint after other checks are performed or data is aggregated.

The following example is a serverless function that can be called at the /say-hey route on the site. When the function is called, it will send the event to the Async Workloads system. At that point, the workload function defined above will run.

TypeScript

TypeScript

import type {Config} from "@netlify/functions";
import { AsyncWorkloadsClient } from "@netlify/async-workloads";

export default async (req: Request) => {

  // do some work... authenticate the user, pull data, etc.

  const client = new AsyncWorkloadsClient();
  await client.send('say-hello');

  return new Response('', { status: 200 });
};

export const config: Config = {
  path: '/say-hey'
}

JavaScript

JavaScript

import { AsyncWorkloadsClient } from "@netlify/async-workloads";

export default async (req) => {

  // do some work... authenticate the user, pull data, etc.

  const client = new AsyncWorkloadsClient();
  await client.send('say-hello');

  return new Response('', { status: 200 });
};

export const config = {
  path: '/say-hey'
}