Use the Defer RedwoodJS CLI Plugin

For projects based on RedwoodJS >= 6.3.0, run the following command

  yarn rw setup package @defer/redwood

This command runs the RedwoodJS CLI Defer plugin that will:

  • install the @defer/client on your RedwoodJS api
  • initialize a Defer client and create a demo helloWorld() background function.

For projects based on RedwoodJS < 6.3.0, please refer to the Custom stack getting started guide.

Create a first background function

A background function is a function equivalent to a background job.

All background functions must live in the defer/ folder shown above.

Choose how to create your first background function:

Our background function is ready to be used; let’s see how to call it from your application.

Call your background function

Whenever you choose to use the helloWorld() function or create your own, the following example showcasing how to call helloWorld() from a RedwoodJS serverless function demonstrates how easily you can trigger a background function execution.

First, generate a RedwoodJS serverless function:

  yarn rw generate function helloWorld
import type { APIGatewayEvent, Context } from "aws-lambda";

import helloWorld from "src/jobs/defer/helloWorld";
import { logger } from "src/lib/logger";

export const handler = async (event: APIGatewayEvent, _context: Context) => {`${event.httpMethod} ${event.path}: runHelloWorld function`);

  await helloWorld(event.queryStringParameters["name"] || "World");

  return {
    statusCode: 200,
    headers: {
      "Content-Type": "application/json",
    body: JSON.stringify({
      ok: true,

To test in local development, first start your RedwoodJS development server:

  yarn rw dev

Then, open your browser and visit the http://localhost:8910/.redwood/functions/helloWorld?name=Charly function endpoint.

Your development log should show the following:

api | 09:09:56 🌲 incoming request GET xxx /helloWorld?name=Charly
api | 09:09:56 🌲 GET /helloWorld: runHelloWorld function
api | 09:09:56 🌲 request completed 1ms
api | 09:10:01 🌲 Hello Charly!

and the response:

{ "ok": true }

How does Defer work locally?

If you are wondering how calling a background function behaves locally, please refer to this guide: Development & Testing.

Once your RedwoodJS function is defined, please commit and push it to your branch.

Now that your RedwoodJS contains a background function and a serverless function that calls it, let’s ensure that your Defer token and Build Settings are correctly configured.

Setup your Node.js / Bun version

Node.js is the default runtime, and version 18.x will be used if you don't specify your own.

Node.js versions 18.x and 20.x are supported, and Bun versions 1.x are supported.

To use Defer with Bun, you need the @defer/client version to be >=1.11.0

To change your runtime and its version, edit the engines field of your package.json:

  "engines": {
    "node": "18.x"

For more details about the supported runtimes, like how dependencies are installed, check our Deploy section


Create your Defer application

First, sign in to the Defer Console, then, go to the “Setup application page.”

Once your application is correctly configured, click the “Create” button.

You should land on the application’s page with a build running; you can go to the Defer Console to check its status.

Your first successful build on the Defer Console

Your first successful build on the Defer Console

You can now get a Defer Token by navigating to the Settings page:

Copy your Defer token

Copy your Defer token for the next step

Configure your API deployment

Your API deployment should expose your Defer Token as an environment variable in order to get your background function deferred when called.


Now, with your API deployment containing your Defer Token and your project’s builds ready on Defer, open your browser and test the RedwoodJS function endpoint.

In the scenario of the helloWorld() background function, visit the /.redwood/functions/helloWorld endpoint of your deployed application.

You should see that your API answered quickly, and by going to your Defer Console, you should see that your background function has 1 execution running - or finished:

Your first function on the Defer Console

By clicking on see executions, you will access the executions list:

Your first successful function un on the Defer Console

Next steps