Connect to data from Server-side Runtimes

This guide walks through how you can connect to Amplify Data from Next.js Server-side Runtimes (SSR). For Next.js applications, Amplify provides first-class support for App Router (React Server Components, Route Handlers, and Server Actions) and Pages Router (Components, API Routes), and Middleware.

Before you begin, you will need:

A Next.js application created
Installed and configured Amplify libraries for Next.js
Deployed Amplify Data resources, or directly using AWS AppSync

Connect to Amplify Data from a Next.js server runtime

Connecting to Amplify Data will include choosing the correct Data client for Next.js server runtimes, generating the Data client, and then calling the API using generated server Data clients.

Step 1 - Choose the correct Data client for Next.js server runtimes

Amplify offers two specialized Data clients for Next.js server runtimes (from @aws-amplify/adapter-nextjs/data) that you should use depending whether you retrieve the user tokens using cookies or NextRequest and NextResponse:

generateServerClientUsingCookies() 🍪 generates a Data client with the Next.js cookies function from next/headers. Each API request dynamically refetches the cookies at runtime.
generateServerClientUsingReqRes() 🌐 generates a Data client requiring NextRequest and NextResponse provided to an runWithAmplifyServerContext function to prevent token contamination.

Choose the correct Data client based on your Next.js Router (App or Pages) and then the use case:

Use case	Required Data client
React Server Component	`generateServerClientUsingCookies()` 🍪
Server Actions	`generateServerClientUsingCookies()` 🍪
Route Handler	`generateServerClientUsingCookies()` 🍪
Middleware	`generateServerClientUsingReqRes()` 🌐

Step 2 - Generate the Data client for Next.js server runtimes

To generate a Data client for the Next.js server runtime using cookies, you need to provide both your Amplify configuration and the cookies function from Next.js.

1import { type Schema } from '@/amplify/data/resource';
2import { generateServerClientUsingCookies } from '@aws-amplify/adapter-nextjs/data';
3import amplifyConfig from '@/amplifyconfiguration.json';
4import { cookies } from 'next/headers';
5
6export const cookieBasedClient = generateServerClientUsingCookies<Schema>({
7  config: amplifyConfig,
8  cookies
9});

We recommend you generate Amplify Data's server client in a utility file. Then, import the generated client in your Next.js React Server Components, Server Actions, or Route Handlers.

Step 3 - Call API using generated server Data clients

You can make any available query or mutation request with the generated server Data clients; however, note that subscriptions are not available within server runtimes.

Import the cookie-based server Data client in your Next.js React Server Component code and make your API requests.

1import { type Schema } from '@/amplify/data/resource'
2import { generateServerClientUsingCookies } from '@aws-amplify/adapter-nextjs/data';
3import amplifyConfig from '@/amplifyconfiguration.json'
4import { cookies } from 'next/headers'
5
6export const cookieBasedClient = generateServerClientUsingCookies<Schema>({
7  config: amplifyConfig,
8  cookies
9})
10
11async fetchTodos() {
12  const { data: todos, errors } = await cookieBasedClient.models.Todo.list()
13
14  if (!errors) {
15    return todos
16  }
17}