Install the @defer/client

yarn add @defer/client

Create a defer/ folder

Defer expects to find all the background functions in the defer/ folder.

In a Nest app, we recommend creating a defer/ folder as follows:

 |-- nest-cli.json
 |-- package.json
 |-- src/
 |   |-- app.controller.spec.ts
 |   |-- app.controller.ts
 |   |-- app.module.ts
 |   |-- app.service.ts
+|   |-- defer/
 |   |-- main.ts
 |-- tsconfig.json
 |-- yarn.lock


All files inside the defer/ folder must be Background Functions (wrapped with defer()); any shared code (ex: utils) should be moved outside of the defer/ folder.

The defer/ folder can be placed anywhere in your project and can contain nested sub-folders.

Write a background function

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

All background functions must live in the defer/ folder.

Choose how to write your first background function:

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

Sidenote: How to use your Nest Services

Using Nest Services from background functions requires some minor plumbing work since background functions behave as what Nest calls “Standalone app”.

For example, your Nest application relies on a standard PrismaService:

import { Injectable, OnModuleInit } from "@nestjs/common";
import { PrismaClient } from "@prisma/client";

export class PrismaService extends PrismaClient implements OnModuleInit {
  async onModuleInit() {
    await this.$connect();

which you can use from your src/defer/syncContacts.ts background function as follows:

import { defer } from "@defer/client";
import { NestFactory } from "@nestjs/core";

import { AppModule } from "src/app.module";
import { PrismaService } from "src/prisma.service";

const getPrismaInstance = async () => {
  const app = await NestFactory.createApplicationContext(AppModule);
  await app.init();
  return app.get(PrismaService);

const syncContacts = async () => {
  const prisma = getPrismaInstance();

  // TODO: use Prisma

export default defer(syncContacts);

The getPrismaInstance() initializes a Nest Application context that will initiate the Services with your application configuration.

The same pattern can be applied to retrieve the Nest application logger, configuration, and other injectable elements.

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 Nest Controller demonstrates how easily you can trigger a background function execution.

import { Controller, Get } from "@nestjs/common";
import { AppService } from "./app.service";
import helloWorld from "./defer/helloWorld";

export class AppController {
  constructor(private readonly appService: AppService) {}

  async getHello(): Promise<string> {
    await helloWorld();
    return this.appService.getHello();

How does Defer work?

If you are wondering how calling a background function triggers an execution on Defer, please refer to this guide: How Defer works.

Once your Nest Controller route is defined, please commit and push it to your branch.

Now that your Nest app contains a background function and an API route that calls it, let’s ensure that your Defer token is configured correctly.

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 Nest Controller route.

In the helloWorld() background function scenario, visit the / route.

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