Server-Side Rendering
This guide walks through how to use Amplify Auth and Data APIs from Next.js server-side runtimes.
Install the Amplify Next.js adapter
To use Amplify APIs server-side, you need to install the Amplify Next.js adapter in addition to the Amplify libraries:
npm add aws-amplify @aws-amplify/adapter-nextjs
Configure Amplify APIs for server-side usage
You will need to create a runWithAmplifyServerContextRunner
function to use Amplify APIs on the server-side of your Next.js app.
You can create an amplifyServerUtils.ts
file under a utils
folder in your codebase. In this file, you will import the Amplify backend outputs from the amplify_outputs.json
file that is generated by the Amplify CLI, and use the createServerRunner
function to create the runWithAmplifyServerContextRunner
function.
For example, the utils/amplifyServerUtils.ts
file may contain the following content:
import { createServerRunner } from '@aws-amplify/adapter-nextjs';import outputs from '@/amplify_outputs.json';
export const { runWithAmplifyServerContext } = createServerRunner({ config: outputs});
You can use the exported runWithAmplifyServerContext
function to call Amplify APIs within isolated request contexts. You can review examples under the Calling Amplify category APIs on the server side section.
Configure Amplify library for client-side usage
When you use the Amplify library on the client-side of your Next.js app, you will need to configure Amplify by calling the Amplify.configure
as you would to use Amplify in a single-page application.
'use client';
import outputs from '@/amplify_outputs.json';import { Amplify } from 'aws-amplify';
Amplify.configure(outputs, { ssr: true // required when using Amplify with Next.js});
export default function RootLayoutThatConfiguresAmplifyOnTheClient({ children}: { children: React.ReactNode;}) { return children;}
Learn moreConfigure Amplify in a Next.js App Router application
If you're using the Next.js App Router, you can create a client component to configure Amplify and import it into your root layout.
ConfigureAmplifyClientSide.ts
:
'use client';
import { Amplify } from 'aws-amplify';import outputs from '../amplify_outputs.json';
Amplify.configure(outputs, { ssr: true });
export default function ConfigureAmplifyClientSide() { return null;}
layout.tsx
:
import ConfigureAmplifyClientSide from '@/components/ConfigureAmplifyClientSide';import './globals.css';
import type { Metadata } from 'next';
export const metadata: Metadata = { title: 'Create Next App', description: 'Generated by create next app',};
export default function RootLayout({ children,}: { children: React.ReactNode;}) { return ( <html lang="en"> <body className="container pb-6"> <> <ConfigureAmplifyClientSide /> {children} </> </body> </html> );}
Authentication with Next.js server-side runtime
You can use the Amplify Auth category APIs to sign up and sign in your end users on the client side. When you set ssr: true
when calling Amplify.configure
, the Amplify library uses cookies to store tokens which will be sent along with HTTP requests to your Next.js app server.
Manage Auth session with the Next.js Middleware
You can use the fetchAuthSession
API to check the auth sessions that are attached to the incoming requests in the middleware of your Next.js app to protect your routes. For example:
import { fetchAuthSession } from 'aws-amplify/auth/server';import { NextRequest, NextResponse } from 'next/server';import { runWithAmplifyServerContext } from '@/utils/amplifyServerUtils';
export async function middleware(request: NextRequest) { const response = NextResponse.next();
const authenticated = await runWithAmplifyServerContext({ nextServerContext: { request, response }, operation: async (contextSpec) => { try { const session = await fetchAuthSession(contextSpec); return ( session.tokens?.accessToken !== undefined && session.tokens?.idToken !== undefined ); } catch (error) { console.log(error); return false; } } });
if (authenticated) { return response; }
return NextResponse.redirect(new URL('/sign-in', request.url));}
export const config = { matcher: [ /* * Match all request paths except for the ones starting with: * - api (API routes) * - _next/static (static files) * - _next/image (image optimization files) * - favicon.ico (favicon file) */ '/((?!api|_next/static|_next/image|favicon.ico|sign-in).*)' ]};
In this example, if the incoming request is not associated with a valid user session the request will be redirected to the /sign-in
route.
Calling Amplify category APIs on the server side
For the Auth categories to use Amplify APIs on the server in your Next.js app, you will need to:
- Import the API from the
/server
sub path. - Use the
runWithAmplifyServerContext
helper function created by calling thecreateServerRunner
function exported from@aws-amplify/adapter-nextjs
to call the Amplify API in an isolated server context.
For the GraphQL API category, review Connect to data from Server-side Runtimes.
With Next.js App Router
Dynamic rendering in React server component
Dynamic rendering is based on a user session extracted from an incoming request.
import { cookies } from 'next/headers';import { getCurrentUser } from 'aws-amplify/auth/server';import { runWithAmplifyServerContext } from '@/utils/amplifyServerUtils';
// This page always dynamically renders per requestexport const dynamic = 'force-dynamic';
export default async function AuthGetCurrentUserServer() { try { const currentUser = await runWithAmplifyServerContext({ nextServerContext: { cookies }, operation: (contextSpec) => getCurrentUser(contextSpec) });
return ( <AuthFetchResult description="The API is called on the server side." data={currentUser} /> ); } catch (error) { console.error(error); return <p>Something went wrong...</p>; }}
Static rendering in React server component
Static rendering does not require a user session, so you can specify the nextServerContext
parameter as null
. This is useful for some use cases; for example, when you are using the Storage API with guest access (if you have enabled it in your backend).
import { getUrl } from 'aws-amplify/storage/server';import Image from 'next/image';import { runWithAmplifyServerContext } from '@/utils/amplifyServerUtils';
// Re-render this page every 60 minutesexport const revalidate = 60 * 60; // in seconds
export default async function StaticallyRenderedPage() { try { const splashUrl = await runWithAmplifyServerContext({ nextServerContext: null, operation: (contextSpec) => getUrl(contextSpec, { key: 'splash.png' }) });
return ( <Image src={splashUrl.url.toString()} alt="Splash Image" width={500} height={500} /> ); } catch (error) { console.error(error); return <p>Something went wrong...</p>; }}
In Route Handlers
In route handlers require implementing an API route that enables GET /apis/get-current-user
.
import { getCurrentUser } from 'aws-amplify/auth/server';import { cookies } from 'next/headers';import { NextResponse } from 'next/server';import { runWithAmplifyServerContext } from '@/utils/amplifyServerUtils';
export async function GET() { const user = await runWithAmplifyServerContext({ nextServerContext: { cookies }, operation: (contextSpec) => getCurrentUser(contextSpec) });
return NextResponse.json({ user });}
When you call fetch('/apis/get-current-user')
it returns a payload that contains the user
data for the current signed-in user.
With Next.js Pages Router
In getServerSideProps
The following example extracts current user data from the request and provides them to a page react component via its props.
export const getServerSideProps: GetServerSideProps = async ({ req, res }) => { const currentUser = await runWithAmplifyServerContext({ nextServerContext: { request: req, response: res }, operation: (contextSpec) => getCurrentUser(contextSpec) });
return { props: { currentUser } };};
In getStaticProps
Similar to static rendering with the App Router, you can pass null
as the value of the nextServerContext
parameter to use the Amplify Storage API with guest access.
export async function getStaticProps() { const splashUrl = await runWithAmplifyServerContext({ nextServerContext: null, operation: (contextSpec) => getUrl(contextSpec, { key: 'splash.png' }) });
return { props: { imageUrl: splashUrl.url.toString() }, revalidate: (splashUrl.expiresAt.getTime() - Date.now()) / 1000 // in seconds };}
Supported APIs for Next.js server-side usage
All APIs that support use on the server are exported from the aws-amplify/<category>/server
sub paths. You must use these APIs for any server-side use cases.
Category | APIs | Server (Node.js) Amplify Hosting/Vercel | Vercel Edge Runtime (middleware) |
---|---|---|---|
Auth | fetchAuthSession | ✅ | ✅ |
Auth | fetchUserAttributes | ✅ | ✅ |
Auth | getCurrentUser | ✅ | ✅ |
Data | generateServerClientUsingCookies | ✅ | |
Data | generateServerClientUsingReqRes | ✅ | |
Storage | getUrl | ✅ | |
Storage | getProperties | ✅ | |
Storage | list | ✅ | |
Storage | remove | ✅ | |
Storage | copy | ✅ |