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
Notes:
- The
defer/
folder can be located anywhere in your project - The
defer/
folder can contain nested 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.
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 });
}
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 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.
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
Disable Server Minification
Next.js experimental server minification is not supported by the Defer Platform.
Starting version 13.5.1
, the serverMinification
experimental feature is
emabled by default.
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.”
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.
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
Was this page helpful?