Next.js server runtime

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 the App Router (React Server Components, Route Handlers, and Server Actions), the 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.

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:

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

import { type Schema } from '@/amplify/data/resource';
import { generateServerClientUsingCookies } from '@aws-amplify/adapter-nextjs/data';
import outputs from '@/amplify_outputs.json';
import { cookies } from 'next/headers';

export const cookieBasedClient = generateServerClientUsingCookies<Schema>({
  config: outputs,
  cookies,
});

import { type Schema } from '@/amplify/data/resource';
import { createServerRunner } from '@aws-amplify/adapter-nextjs';
import { generateServerClientUsingReqRes } from '@aws-amplify/adapter-nextjs/data';
import outputs from '@/amplify_outputs.json';

export const { runWithAmplifyServerContext } = createServerRunner({
  config: outputs,
});

export const reqResBasedClient = generateServerClientUsingReqRes<Schema>({
  config: outputs,
});

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 { type Schema } from '@/amplify/data/resource';
import { generateServerClientUsingCookies } from '@aws-amplify/adapter-nextjs/data';
import outputs from '@/amplify_outputs.json';
import { cookies } from 'next/headers';

export const cookieBasedClient = generateServerClientUsingCookies<Schema>({
  config: outputs,
  cookies,
});

const fetchTodos = async () => {
  const { data: todos, errors } = await cookieBasedClient.models.Todo.list();

  if (!errors) {
    return todos;
  }
};

import { type Schema } from '@/amplify/data/resource';
import type { NextApiRequest, NextApiResponse } from 'next';
import {
  runWithAmplifyServerContext,
  reqResBasedClient,
} from '@/utils/amplifyServerUtils';

type ResponseData = {
  todos: Schema['Todo']['type'][];
};

export default async function handler(
  request: NextApiRequest,
  response: NextApiResponse<ResponseData>
) {
  const todos = await runWithAmplifyServerContext({
    nextServerContext: { request, response },
    operation: async (contextSpec) => {
      const { data: todos } = await reqResBasedClient.models.Todo.list(
        contextSpec
      );
      return todos;
    },
  });

  response.status(200).json({ todos });
}