Getting started with Next.js

​

Setup

​

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 Next.js app, we recommend creating a defer/ folder as follows:

 .
 |-- pages/
 |-- styles/
+|-- defer/
 |-- next-env.d.ts
 |-- next.config.js
 |-- package.json
 |-- tsconfig.json
 |-- package-lock.json

​

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:

// the `defer()` helper will be used to define a background function
import { defer } from "@defer/client";

// a background function must be `async`
async function helloWorld(name: string) {
  return new Promise((resolve) => {
    setTimeout(() => {
      console.log(`Hello ${name}!`);
      resolve("done");
    }, 5000);
  });
}

// the function must be wrapped with `defer()` and exported as default
export default defer(helloWorld);

// the `defer()` helper will be used to define a background function
import { defer } from "@defer/client"
// the `defer()` helper will be used to define a background function
import syncContacts from "../utils/syncContacts"

// the imported function must be wrapped with `defer()` and re-exported as default
export default defer(syncContacts)

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 Next.js API route demonstrates how easily you can trigger a background function execution.

import type { NextApiRequest, NextApiResponse } from "next";
// we import our `helloWorld()` background function
import helloWorld from "../../defer/helloWorld";

type Data = {
  ok: boolean;
};

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse<Data>,
) {
  // calling a background function triggers an execution on Defer Platform
  await helloWorld("Charly");

  res.status(200).json({ ok: true });
}

Once your Next.js API Route is defined, please commit and push it to your branch.

Now that your Next.js app contains a background function and an API route that calls it; let’s ensure that your Defer token is properly 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.

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

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

​

Disable Server Minification

Next.js experimental server minification is not supported by the Defer Platform.

To use Defer, please edit your next.config.js or next.config.mjs file and disable experimental.serverMinification if not already done:

/** @type {import('next').NextConfig} */
const nextConfig = {
  /* ... */
  experimental: {
    serverMinification: false,
  },
  /* ... */
};

module.exports = nextConfig;

​

Configure

​

Create your Defer application

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

1. Selecting a repository

Install Defer on your GitHub account or organization on so Defer can list your repositories:

Ensure to install Defer on your GitHub account

Then, select the GitHub repository of your application:

2. Environment variables (ex: Database access)

The background functions that run in Defer might need to access some externally configured services or databases. For this reason, we recommend using the same environment variables configuration for your target API environment and Defer application.

Got a .env file?

Copy the file’s content into your clipboard and paste it into the first field of the “Add” line. ✨

Note: Monorepo, Prisma

If your application resides in a mono repo or relies on Prisma, please refer to the Builds page on advanced options.

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

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

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.

Set your Defer Token on Vercel

1. Go to your Vercel Dashboard
2. From your project, go to settings
3. Then, to “Environment Variables”
4. Finally, add a new environment variable with Key as DEFER_TOKEN:

Set your Defer Token on Heroku

1. Go to your Heroku Dashboard
2. Select your app, and go to settings
3. Scroll to “Config Vars” and click on “Reveal Config Vars”
4. Finally, add a new environment variable with DEFER_TOKEN as “key”:

Set your Defer Token on Render

1. Go to your Render Dashboard
2. Select a service
3. Then, go to “Environment” and click on Add Environment Variable
4. Finally, add a new environment variable with DEFER_TOKEN as “key”:

Set your Defer Token on Fly.io

Update your fly.toml configuration filename as follow:

filename="fly.toml" {3} copy

[env]
MY_ENV = "debug"
DEFER_TOKEN = "<your defer token>"

Set your Defer Token on other hosting providers

Update your environment variables by adding the following:

• key: "DEFER_TOKEN"
• value: your Defer Token

​

Deploy

Now, with your API deployment containing your Defer Token and your project’s builds ready on Defer, open your browser and test the Next.js API Route.

In the scenario of the helloWorld() background function, visit the /api/helloWorld 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:

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

​

Next steps