diff --git a/packages/adapter-nextjs/src/runWithAmplifyServerContext.ts b/packages/adapter-nextjs/src/runWithAmplifyServerContext.ts index 9e6d6e89110..0f348b78242 100644 --- a/packages/adapter-nextjs/src/runWithAmplifyServerContext.ts +++ b/packages/adapter-nextjs/src/runWithAmplifyServerContext.ts @@ -14,6 +14,49 @@ import { runWithAmplifyServerContext as runWithAmplifyServerContextCore, } from 'aws-amplify/internals/adapter-core'; +/** + * Runs the {@link operation} with the the context created from the {@link nextServerContext}. + * + * @param input The input to call the {@link runWithAmplifyServerContext}. + * @param input.nextServerContext The Next.js server context. It varies depends + * where the {@link runWithAmplifyServerContext} is being called. + * - In the [middleware](https://nextjs.org/docs/app/building-your-application/routing/middleware): + * the context consists of an instance of the `NextRequest` and an instance + * of the `NextResponse`. + * - In a [Page server component](https://nextjs.org/docs/app/building-your-application/routing/pages-and-layouts#pages): + * the context is the [`cookies`](https://nextjs.org/docs/app/api-reference/functions/cookies) + * function provided by Next.js. + * - In a [Route Handler](https://nextjs.org/docs/app/building-your-application/routing/route-handlers): + * the context can be the [`cookies`](https://nextjs.org/docs/app/api-reference/functions/cookies) + * function or a combination of an instance of the `NextRequest` and an instance + * of the `NextResponse`. + * - In a [Server Action](https://nextjs.org/docs/app/building-your-application/data-fetching/forms-and-mutations#how-server-actions-work): + * the context is the [`cookies`](https://nextjs.org/docs/app/api-reference/functions/cookies) + * function provided by Next.js. + * @param input.operation The function that contains the business logic calling + * Amplify APIs. It expects a `contextSpec` parameter. + * @returns The result returned by the {@link operation}. + * @example + * // Use the `fetchAuthSession` API in the Next.js `middleware`. + * import { NextRequest, NextResponse } from "next/server"; + * import { fetchAuthSession } from "aws-amplify/auth/server"; + * import { runWithAmplifyServerContext } from "@aws-amplify/adapter-nextjs"; + + * export async function middleware(request: NextRequest) { + * const response = NextResponse.next(); + * const authenticated = await runWithAmplifyServerContext({ + * nextServerContext: { request, response }, + * operation: async (contextSpec) => { + * const session = await fetchAuthSession(contextSpec); + * return session.tokens !== undefined; + * } + * }); + * if (authenticated) { + * return response; + * } + * return NextResponse.redirect(new URL('/sign-in', request.url)); + * } + */ export const runWithAmplifyServerContext: NextServer.RunOperationWithContext = async ({ nextServerContext, operation }) => { // 1. get amplify config from env vars diff --git a/packages/adapter-nextjs/src/types/NextServer.ts b/packages/adapter-nextjs/src/types/NextServer.ts index ed7d8d79ae9..ed9f31ba606 100644 --- a/packages/adapter-nextjs/src/types/NextServer.ts +++ b/packages/adapter-nextjs/src/types/NextServer.ts @@ -51,12 +51,18 @@ export namespace NextServer { response: NextGetServerSidePropsContext['res']; }; + /** + * The union of possible Next.js app server context types. + */ export type Context = | NextRequestAndNextResponseContext | NextRequestAndResponseContext | ServerComponentContext | GetServerSidePropsContext; + /** + * The interface of the input of {@link RunOperationWithContext}. + */ export interface RunWithContextInput { nextServerContext: Context | null; operation: ( diff --git a/packages/adapter-nextjs/tslint.json b/packages/adapter-nextjs/tslint.json index 8eafab1d2b4..fcca611fccf 100644 --- a/packages/adapter-nextjs/tslint.json +++ b/packages/adapter-nextjs/tslint.json @@ -5,7 +5,13 @@ "jsRules": {}, "rules": { "prefer-const": true, - "max-line-length": [true, 120], + "max-line-length": [ + true, + { + "limit": 120, + "ignore-pattern": "^//|^ *" + } + ], "no-empty-interface": true, "no-var-keyword": true, "object-literal-shorthand": true,