chore: rearrange content sectioins

Author: HuiSF

src/pages/[platform]/build-a-backend/server-side-rendering/index.mdx

@@ -38,17 +38,28 @@ Before you begin:
 
 ## Install the Amplify Next.js adapter
 
+<Callout warning>
+
+**Note:** Amplify JS v6 supports Next.js with the version range: `>=13.5.0 <16.0.0`.
+Ensure you have the correct version to integrate with Amplify.
+
+</Callout>
+
 To use Amplify APIs server-side, you need to install the Amplify Next.js adapter in addition to the Amplify libraries:
 
 ```bash title="Terminal" showLineNumbers={false}
 npm add aws-amplify @aws-amplify/adapter-nextjs
 ```
 
-## Configure Amplify APIs for server-side usage
+## Configure Amplify in Next.js
 
-You will need to create a `runWithAmplifyServerContextRunner` function to use Amplify APIs on the server-side of your Next.js app.
+<BlockSwitcher>
+
+<Block name="Configure Amplify for server-side usage">
 
-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.
+You will need to create a `runWithAmplifyServerContext` 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 `runWithAmplifyServerContext` function.
 
 For example, the `utils/amplifyServerUtils.ts` file may contain the following content:
 
@@ -64,16 +75,21 @@ export const { runWithAmplifyServerContext } = createServerRunner({
 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](#calling-amplify-category-apis-on-the-server-side) section.
 
 <Callout>
-**TIP:** You only need to call the `createServerRunner` function once and reuse the `runWithAmplifyServerContext` function throughout.
+**Tip:** You only need to call the `createServerRunner` function once and reuse the `runWithAmplifyServerContext` function throughout.
 </Callout>
 
-## Configure Amplify library for client-side usage
+</Block>
+<Block name="Configure Amplify for client-side usage">
+
+<Callout>
+**Tip**: You only need do this step if you are using Amplify APIs on the client side of your Next.js app, for example, calling Amplify Auth `signIn` API to sign in a user, or use GraphQL subscriptions on the client side.
+</Callout>
 
 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.
 
 <Callout>
 
-**NOTE:** To use the Amplify library on the client side in a Next.js app, you will need to set `ssr` to `true` when calling `Amplify.configure`. This instructs the Amplify library to store tokens in the cookie store of a browser. Cookies will be sent along with requests to your Next.js server for authentication.
+**Note:** To use the Amplify library on the client side in a Next.js app, you will need to set `ssr` to `true` when calling `Amplify.configure`. This instructs the Amplify library to store tokens in the cookie store of a browser. Cookies will be sent along with requests to your Next.js server for authentication.
 
 </Callout>
 
@@ -96,6 +112,12 @@ export default function RootLayoutThatConfiguresAmplifyOnTheClient({
 }
 ```
 
+<Callout warning>
+
+Make sure you call `Amplify.configure` as early as possible in your application’s life-cycle. A missing configuration or `NoCredentials` error is thrown if `Amplify.configure` has not been called before other Amplify JavaScript APIs. Review the [Library Not Configured Troubleshooting guide](/gen1/[platform]/build-a-backend/troubleshooting/library-not-configured/) for possible causes of this issue.
+
+</Callout>
+
 <Callout>
 
 To avoid repetitive calls to `Amplify.configure`, you can call it once in a top-level client-side rendered layout component.
@@ -154,79 +176,25 @@ export default function RootLayout({
 
 </Accordion>
 
-## 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:
-
-```typescript title="src/middleware.ts"
-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).*)'
-  ]
-};
-```
+</Block>
 
-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.
+</BlockSwitcher>
 
-<Callout>
 
-**NOTE:** When calling `fetchAuthSession` with a `response` context, it will send the refreshed tokens (if any) back to the client via the `Set-Cookie` header in the response.
 
-</Callout>
+## Authentication with Next.js server-side runtime
 
 ### (Experimental) Perform authentication on the server side and enable HttpOnly cookies
 
 <Callout warning>
 
-**Warning:** Once you enable the server-side sign-in feature, auth tokens are stored in HttpOnly cookies and you may not change the HttpOnly attribute. Since these cookies are inaccessible from client-side scripts, you won’t be able to use any Amplify JS APIs on the client side. Therefore, you don’t need to configure Amplify on the client side. You can keep using [these Amplify JS server-side APIs](/[platform]/build-a-backend/server-side-rendering/#supported-apis-for-nextjs-server-side-usage) on the server side.
-
-</Callout>
+**Warning:** This feature is experimental and may change in future releases.
 
-**Prerequisites**
+Once you enable the server-side sign-in feature, auth tokens are stored in HttpOnly cookies and you may not change the HttpOnly attribute. Since these cookies are inaccessible from client-side scripts, you won’t be able to use any Amplify JS APIs on the client side. Therefore, you don’t need to configure Amplify on the client side. You can keep using [these Amplify JS server-side APIs](/[platform]/build-a-backend/server-side-rendering/#supported-apis-for-nextjs-server-side-usage) on the server side.
 
-To authenticate users on the server side, you must enable either Amazon Cognito Managed Login or Hosted UI in your Amazon Cognito User Pool client.
+</Callout>
 
+Additional setup is required to enable server-side authentication flows in your Next.js app. 
 
 #### Step 1 - Specify the origin of your app in environment variables
 
@@ -322,17 +290,18 @@ You can provide the callback API routes as the redirect URLs in the Auth resourc
 export const auth = defineAuth({
   loginWith: {
     email: true,
+    // highlight-start
     externalProviders: {
-      google: {/* ... */},
-      // highlight-start
       callbackUrls: ["https://myapp.com/api/auth/sign-in-callback"],
       logoutUrls: ["https://myapp.com/api/auth/sign-out-callback"],
-      // highlight-end
     },
+    // highlight-end
   },
 });
 ```
 
+This enables Amazon Cognito Hosted UI to support the server-side authentication flows. You may upgrade to the latest Amazon Cognito Managed Login Branding to customize the sign-in and sign-up pages. See [Amazon Cognito user pool managed login](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-managed-login.html) for more information.
+
 #### Step 5 - Use Anchor link for initiating server-side authentication flows
 
 Use HTML anchor links to navigate users to the sign-in and sign-up routes. For example:
@@ -386,6 +355,63 @@ export const SignOutButton() {
 
 When an end user clicks on the buttons above, a corresponding server-side authentication flow will be initiated.
 
+### Validate user 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:
+
+```typescript title="src/middleware.ts"
+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.
+
+<Callout>
+
+**Note:** When calling `fetchAuthSession` with a `response` context, it will send the refreshed tokens (if any) back to the client via the `Set-Cookie` header in the response.
+
+</Callout>
+
 ## 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:
@@ -397,7 +423,7 @@ For the **GraphQL API** category, review [Connect to data from Server-side Runti
 
 <Callout>
 
-**NOTE:** A subset of Amplify APIs can now be called on the server side of a Next.js app. These APIs are exported from the `/server` sub paths. See [the full list](#supported-apis-for-nextjs-server-side-usage) of supported APIs.
+**Note:** A subset of Amplify APIs can now be called on the server side of a Next.js app. These APIs are exported from the `/server` sub paths. See [the full list](#supported-apis-for-nextjs-server-side-usage) of supported APIs.
 
 </Callout>
 
@@ -445,10 +471,7 @@ export default async function AuthGetCurrentUserServer() {
     });
 
     return (
-      <AuthFetchResult
-        description="The API is called on the server side."
-        data={currentUser}
-      />
+      <p>{`Hello, ${currentUser.username}`}</p>
     );
   } catch (error) {
     console.error(error);
@@ -496,7 +519,7 @@ export default async function StaticallyRenderedPage() {
 
 <Callout>
 
-**NOTE:** The URL returned by the `getUrl` API expires in the above example. You may want to specify the `revalidate` parameter to rerender the page as required to ensure the URL gets regenerated.
+**Note:** The URL returned by the `getUrl` API expires in the above example. You may want to specify the `revalidate` parameter to rerender the page as required to ensure the URL gets regenerated.
 
 </Callout>