From 641771f35280e34f0d29160a76ee83c266b2e131 Mon Sep 17 00:00:00 2001
From: Hui Zhao <zhohz@amazon.com>
Date: Mon, 3 Feb 2025 15:15:18 -0800
Subject: [PATCH 1/2] chore(adapter-nextjs): update tsdoc of the public APIs

---
 packages/adapter-nextjs/src/types/NextServer.ts | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/packages/adapter-nextjs/src/types/NextServer.ts b/packages/adapter-nextjs/src/types/NextServer.ts
index 3bdfb594fb5..c79075055fa 100644
--- a/packages/adapter-nextjs/src/types/NextServer.ts
+++ b/packages/adapter-nextjs/src/types/NextServer.ts
@@ -91,7 +91,20 @@ export declare namespace NextServer {
 	}
 
 	export interface CreateServerRunnerOutput {
+		/**
+		 * The function to run an operation with the Amplify server context. The operation is a callback function that
+		 * takes a context spec parameter which is used to call the Amplify-side server APIs. The result of the operation
+		 * is returned as a promise.
+		 */
 		runWithAmplifyServerContext: RunOperationWithContext;
+		/**
+		 * The factory function to create the route handlers for the Amplify server-side authentication. You can call this
+		 * function and export the result as the route handlers in the Next.js API routes, to authenticate your end users
+		 * on the server side.
+		 *
+		 * Note: when enabling server-side authentication, Amplify APIs can no longer be used in the client-side.
+		 * @experimental
+		 */
 		createAuthRouteHandlers: CreateAuthRouteHandlers;
 	}
 

From 8766addf9d4d77c751d60b670d8ba1e57f359328 Mon Sep 17 00:00:00 2001
From: Hui Zhao <zhohz@amazon.com>
Date: Thu, 6 Feb 2025 17:32:46 -0800
Subject: [PATCH 2/2] chore: add @example

---
 .../adapter-nextjs/src/types/NextServer.ts    | 65 +++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/packages/adapter-nextjs/src/types/NextServer.ts b/packages/adapter-nextjs/src/types/NextServer.ts
index c79075055fa..4c04829a198 100644
--- a/packages/adapter-nextjs/src/types/NextServer.ts
+++ b/packages/adapter-nextjs/src/types/NextServer.ts
@@ -95,6 +95,46 @@ export declare namespace NextServer {
 		 * The function to run an operation with the Amplify server context. The operation is a callback function that
 		 * takes a context spec parameter which is used to call the Amplify-side server APIs. The result of the operation
 		 * is returned as a promise.
+		 *
+		 * @example
+		 * ```
+		 * // In `src/amplifyUtils.ts`
+		 * import { createServerRunner } from 'aws-amplify/adapter-nextjs';
+		 * import outputs from '@/amplify_outputs.json';
+		 *
+		 * export const { runWithAmplifyServerContext } = createServerRunner({ config: outputs });
+		 *
+		 * // In `src/app/home/page.tsx` (App router)
+		 * import { cookies } from 'next/headers';
+		 * import { runWithAmplifyServerContext } from '@/amplifyUtils';
+		 *
+		 * export default async function HomePage() {
+		 *   const user = await runWithAmplifyServerContext({
+		 *     nextServerContext: { cookies },
+		 *     operation: (contextSpec) => getCurrentUser(contextSpec),
+		 *   });
+		 *
+		 *  return <div>{`Hello, ${user.username}`}</div>;
+		 * }
+		 *
+		 * // In `src/pages/home/index.tsx` (Pages router)
+		 * import { runWithAmplifyServerContext } from '@/amplifyUtils';
+		 *
+		 * export const getServerSideProps = async ({ req, res }) => {
+		 *   const user = await runWithAmplifyServerContext({
+		 *     nextServerContext: { request: req, response: res },
+		 *     operation: (contextSpec) => getCurrentUser(contextSpec),
+		 *   });
+		 *
+		 *   return {
+		 *     props: { user },
+		 *   }
+		 * }
+		 *
+		 * export default function HomePage(props) {
+		 *   return <div>{`Hello, ${props.user.username}`}</div>;
+		 * }
+		 * ```
 		 */
 		runWithAmplifyServerContext: RunOperationWithContext;
 		/**
@@ -104,6 +144,31 @@ export declare namespace NextServer {
 		 *
 		 * Note: when enabling server-side authentication, Amplify APIs can no longer be used in the client-side.
 		 * @experimental
+		 *
+		 * @example
+		 * ```
+		 * // In `src/amplifyUtils.ts`
+		 * import { createServerRunner } from 'aws-amplify/adapter-nextjs';
+		 * import outputs from '@/amplify_outputs.json';
+		 *
+		 * export const { createAuthRouteHandlers } = createServerRunner({ config: outputs });
+		 *
+		 * // In `src/app/api/auth/[slug]/route.tsx` (App router)
+		 * import { createAuthRouteHandlers } from '@/amplifyUtils';
+		 *
+		 * export const GET = createAuthRouteHandlers({
+		 *   redirectOnSignInComplete: "/home",
+		 *   redirectOnSignOutComplete: "/sign-in",
+		 * );
+		 *
+		 * // In `src/pages/api/auth/[slug].tsx` (Pages router)
+		 * import { createAuthRouteHandlers } from '@/amplifyUtils';
+		 *
+		 * export default createAuthRouteHandlers({
+		 *   redirectOnSignInComplete: "/home",
+		 *   redirectOnSignOutComplete: "/sign-in",
+		 * });
+		 * ```
 		 */
 		createAuthRouteHandlers: CreateAuthRouteHandlers;
 	}