Next.js App Router (Server Components)

This Quickstart guide will walk you through how to build a task list application with TypeScript, Next.js App Router with Server Components, and React. If you are new to these technologies, we recommend you go through the official React, Next.js, and TypeScript tutorials first.

Prerequisites

Before you get started, make sure you have the following installed:

• Node.js v18.17 or later
• npm v9 or later
• git v2.14.1 or later

You will also need to create an AWS account. Note that AWS Amplify is part of the AWS Free Tier.

Create a project

First, you will need to create a new Next.js app. The following command will create a Next.js app in a directory called next-amplify-gen2 that uses the App Router.

npm create next-app@14 -- next-amplify-gen2 --typescript --eslint --app --no-src-dir --no-tailwind --import-alias '@/*'
cd next-amplify-gen2

The easiest way to get started with AWS Amplify is through npm with create-amplify.

npm create amplify@latest

? Where should we create your project? (.) # press enter

Running this command will scaffold a lightweight Amplify project in your current project with the following files:

├── amplify/
│   ├── auth/
│   │   └── resource.ts
│   ├── data/
│   │   └── resource.ts
│   ├── backend.ts
│   └── package.json
├── node_modules/
├── .gitignore
├── package-lock.json
├── package.json
└── tsconfig.json

Start local dev server

Let's start a local dev server for your app development. For the frontend, run npm run dev to spin up a localhost dev server with the default Next.js template.

npm run dev

For the backend, we're going to start a cloud sandbox environment. Amplify gives every developer a personal cloud sandbox environment that provides isolated development spaces to rapidly build, test, and iterate. When you're working with a team, each developer will have their own personal cloud sandbox. In a new terminal window, run the following command:

npx ampx sandbox

You should now have these two commands running concurrently in different terminal windows.

Build a backend

Next, we will add data and auth capabilities to the app. In Amplify Gen 2, the resource.ts files are where you define the corresponding backend resource and details about it.

Add data

create-amplify provides the scaffolding of a amplify/data/resource.ts file, which is ready to deploy.

import { type ClientSchema, a, defineData } from '@aws-amplify/backend';

/*== STEP 1 ===============================================================
The section below creates a Todo database table with a "content" field. Try
adding a new "isDone" field as a boolean. The authorization rules below
specify that owners, authenticated via your Auth resource, can "create",
"read", "update", and "delete" their own records. Public users,
authenticated via an API key, can only "read" records.
=========================================================================*/
const schema = a.schema({
  Todo: a
    .model({
      content: a.string()
    })
    .authorization(allow => [allow.owner(), allow.publicApiKey().to(['read'])])
});

export type Schema = ClientSchema<typeof schema>;

export const data = defineData({
  schema,
  authorizationModes: {
    defaultAuthorizationMode: 'apiKey',
    // API Key is used for allow.publicApiKey() rules
    apiKeyAuthorizationMode: {
      expiresInDays: 30
    }
  }
});

/*== STEP 2 ===============================================================
Go to your frontend source code. From your client-side code, generate a
Data client to make CRUDL requests to your table. (THIS SNIPPET WILL ONLY
WORK IN THE FRONTEND CODE FILE.)

Using JavaScript or Next.js React Server Components, Middleware, Server
Actions, or Pages Router? Review how to generate Data clients for those use
cases: https://docs.amplify.aws/react/build-a-backend/data/connect-to-API/
=========================================================================*/

/*
"use client"
import { generateClient } from "aws-amplify/data";
import { type Schema } from "@/amplify/data/resource";

const client = generateClient<Schema>() // use this Data client for CRUDL requests
*/

/*== STEP 3 ===============================================================
Fetch records from the database and use them in your frontend component.
(THIS SNIPPET WILL ONLY WORK IN THE FRONTEND CODE FILE.)
=========================================================================*/

/* For example, in a React component, you can use this snippet in your
  function's RETURN statement */
// const { data: todos } = client.models.Todo.list()

// return <ul>{todos.map(todo => <li key={todo.id}>{todo.content}</li>)}</ul>

Step 1: Open amplify/data/resource.ts and update it to add a done field of type boolean and a priority field of enum with a value of ['low', 'medium', 'high']. We've removed the default comments to shorten the code below for the next few examples.

import { type ClientSchema, a, defineData } from '@aws-amplify/backend';

// ...

const schema = a.schema({
  Todo: a
    .model({
      content: a.string(),
Copy highlighted code example
      done: a.boolean(),
      priority: a.enum(['low', 'medium', 'high'])
    })
    .authorization(allow => [allow.owner(), allow.publicApiKey().to(['read'])]),
});

// ...

Once you save your changes to the data model, they will be deployed in seconds to your cloud sandbox.

The Todo data model is defined with authorization rules to allow the person who creates the Todo instance (the owner) to perform all actions on the data they own. We are also allowing all page viewers, including unauthenticated users, to read data.

Step 2: Remove public access by deleting the allow.publicApiKey().to(['read']) authorization rule. Your authorization rule will look like the code below:

// ...

.authorization(allow => [allow.owner()]),

// ...

Below the schema declaration, you will see the defineData function, which receives our schema and authorization configuration as arguments. The default configuration is for an apiKey to enable public access.

Step 3: Update the defaultAuthorizationMode to userPool so that the default is to use user authentication.

// ...

export const data = defineData({
  schema,
  authorizationModes: {
    defaultAuthorizationMode: 'userPool'
  }
});

Add authentication

Now let's work on our authentication configuration. Similar to the data/resource.ts we just worked on, the auth/resource.ts file has code to define our authentication configuration. In this case, we are setting the authentication method to log in with email.

import { defineAuth } from '@aws-amplify/backend';

/**
 * Define and configure your auth resource
 * When used alongside data, it is automatically configured as an auth provider for data
 * @see https://docs.amplify.aws/gen2/build-a-backend/auth
 */
export const auth = defineAuth({
  loginWith: {
    email: true,
    // add social providers
    externalProviders: {
      /**
       * first, create your secrets using `amplify sandbox secret`
       * then, import `secret` from `@aws-amplify/backend`
       * @see https://docs.amplify.aws/gen2/deploy-and-host/sandbox-environments/features/#setting-secrets
       */
      // loginWithAmazon: {
      //   clientId: secret('LOGINWITHAMAZON_CLIENT_ID'),
      //   clientSecret: secret('LOGINWITHAMAZON_CLIENT_SECRET'),
      // }
    }
  },
  /**
   * enable multifactor authentication
   * @see https://docs.amplify.aws/gen2/build-a-backend/auth/manage-mfa
   */
  // multifactor: {
  //   mode: 'OPTIONAL',
  //   sms: {
  //     smsMessage: (code) => `Your verification code is ${code}`,
  //   },
  // },
  userAttributes: {
    /** request additional attributes for your app's users */
    // profilePicture: {
    //   mutable: true,
    //   required: false,
    // },
  }
});

Let's customize the subject of the verification email sent to users after they sign up for our app. There is only one step to complete.

Open amplify/auth/resource.ts and update it to add a subject line by defining an object with email authentication properties referencing the code below:

// amplify/auth/resource.ts
import { defineAuth } from '@aws-amplify/backend';

export const auth = defineAuth({
  loginWith: {
Copy highlighted code example
   email: {
     verificationEmailSubject: 'Welcome! Verify your email!'
   },
  }
});

import { defineBackend } from '@aws-amplify/backend';
import { auth } from './auth/resource';
import { data } from './data/resource';

defineBackend({
  auth,
  data
});

Build UI

Let's add UI that connects to the backend data and auth resources.

Configure Amplify Client Side

First, install the Amplify UI component library:

npm add @aws-amplify/ui-react

Next, create a components folder in the root of your project and copy the contents below to a file called ConfigureAmplify.tsx.

// components/ConfigureAmplify.tsx
"use client";

import { Amplify } from "aws-amplify";

import outputs from "@/amplify_outputs.json";

Amplify.configure(outputs, { ssr: true });

export default function ConfigureAmplifyClientSide() {
  return null;
}

Update app/layout.tsx to import and render <ConfigureAmplifyClientSide />. This client component will configure Amplify for client pages in our application.

// app/layout.tsx
import "@aws-amplify/ui-react/styles.css";
import type { Metadata } from "next";
import { Inter } from "next/font/google";
import "./globals.css";

import ConfigureAmplifyClientSide from "@/components/ConfigureAmplify";

const inter = Inter({ subsets: ["latin"] });

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={inter.className}>
        <ConfigureAmplifyClientSide />
        {children}
      </body>
    </html>
  );
}

Configure Amplify Server Side

First, install the Amplify Next.js adapter:

npm add @aws-amplify/adapter-nextjs

Next, create a utils/amplify-utils.ts file from the root of the project and paste the code below. runWithAmplifyServerContext, cookiesClient, and AuthGetCurrentUserServer are declared here and will be used to gain access to Amplify assets from the server.

// utils/amplify-utils.ts
import { cookies } from "next/headers";

import { createServerRunner } from "@aws-amplify/adapter-nextjs";
import { generateServerClientUsingCookies } from "@aws-amplify/adapter-nextjs/api";
import { getCurrentUser } from "aws-amplify/auth/server";

import { type Schema } from "@/amplify/data/resource";
import outputs from "@/amplify_outputs.json";

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

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

export async function AuthGetCurrentUserServer() {
  try {
    const currentUser = await runWithAmplifyServerContext({
      nextServerContext: { cookies },
      operation: (contextSpec) => getCurrentUser(contextSpec),
    });
    return currentUser;
  } catch (error) {
    console.error(error);
  }
}

Add server authentication routes

First, create a client-side Login component in the components folder that will be wrapped in withAuthenticator. If the user is logged in, they will be redirected to the index route; otherwise, the Amplify UI Authenticator component will be rendered.

// components/Login.tsx
"use client";

import { withAuthenticator } from "@aws-amplify/ui-react";
import { AuthUser } from "aws-amplify/auth";
import { redirect } from "next/navigation";
import { useEffect } from "react";

function Login({ user }: { user?: AuthUser }) {
  useEffect(() => {
    if (user) {
      redirect("/");
    }
  }, [user]);
  return null;
}

export default withAuthenticator(Login);

Next, create a new route under app/login/page.tsx to render the Login component.

// app/login/page.tsx

import Login from "@/components/Login";

export default function LoginPage() {
  return <Login />;
}

// app/login/page.tsx - Custom <Authenticator>

"use client";

import {
  Authenticator,
  Text,
  View,
  useAuthenticator,
} from "@aws-amplify/ui-react";
import { redirect } from "next/navigation";
import { useEffect } from "react";

const components = {
  Header() {
    return (
      <View textAlign="center">
        <Text><span style={{color: "white"}}>Authenticator Header</span></Text>
      </View>
    );
  },
};

function CustomAuthenticator() {
  const { user } = useAuthenticator((context) => [context.user]);

  useEffect(() => {
    if (user) {
      redirect("/");
    }
  }, [user]);

  return <Authenticator components={components} />;
}

export default function Login() {
  return (
    <Authenticator.Provider>
      <CustomAuthenticator />
    </Authenticator.Provider>
  );
}

Finally, create a Logout component to be used later.

// components/Logout.tsx

"use client";

import { signOut } from "aws-amplify/auth";
import { useRouter } from "next/navigation";

export default function Logout() {
  const router = useRouter();

  return (
    <button
      onClick={async () => {
        await signOut();
        router.push("/login");
      }}
      className="px-2 bg-white text-black"
    >
      Sign out
    </button>
  );
}

import { defineAuth, secret } from '@aws-amplify/backend';

export const auth = defineAuth({
  loginWith: {
    externalProviders: {
      // ...
      callbackUrls: [
        'http://localhost:3000/login',
        'https://mywebsite.com/login'
      ],
      logoutUrls: ['http://localhost:3000/logout', 'https://mywebsite.com/logout']
    }
  }
});

Add middleware for server-side redirect

Create middleware.ts in the root of the project with the contents below.

This middleware runs fetchAuthSession wrapped in runWithAmplifyServerContext and will redirect to /login when a user is not logged in.

// middleware.ts
import { NextRequest, NextResponse } from "next/server";

import { fetchAuthSession } from "aws-amplify/auth/server";

import { runWithAmplifyServerContext } from "@/utils/amplify-utils";

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 !== undefined;
      } catch (error) {
        console.log(error);
        return false;
      }
    },
  });

  if (authenticated) {
    return response;
  }

  return NextResponse.redirect(new URL("/login", 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)
     * - login
     */
    "/((?!api|_next/static|_next/image|favicon.ico|login).*)",
  ],
};

Run your application with npm run dev and navigate to http://localhost:3000. You should now see the authenticator, which is already configured and ready for your first sign-up! Create a new user account, confirm the account through email, and then sign in.

View list of to-do items

Now, let's display data on our app's frontend.

The code below uses the cookiesClient to provide access to the Todo model defined in the backend.

Modify your app's home page file, app/page.tsx, with the following code:

// app/page.tsx

import { cookiesClient } from "@/utils/amplify-utils";

async function App() {
  const { data: todos } = await cookiesClient.models.Todo.list();

  return (
    <>
      <h1>Hello, Amplify 👋</h1>
      <ul>
        {todos && todos.map((todo) => <li key={todo.id}>{todo.content}</li>)}
      </ul>
    </>
  );
}

export default App;

Once you save the file and navigate back to http://localhost:3000, you should see "Hello, Amplify" with a blank page for now because you have only an empty list of to-dos.

Create a new to-do item

Let's update the component to have a form for prompting the user for the title for creating a new to-do list item and run the addTodo method on form submission. In a production app, the additional fields of the Todo model would be added to the form.

After creating a to-do, revalidatePath is run to clear the Next.js cache for this route to instantly update the results from the server without a full page reload.

// app/page.tsx

import { revalidatePath } from "next/cache";

import { AuthGetCurrentUserServer, cookiesClient } from "@/utils/amplify-utils";

import Logout from "@/components/Logout";

async function App() {
  const user = await AuthGetCurrentUserServer();
  const { data: todos } = await cookiesClient.models.Todo.list();

  async function addTodo(data: FormData) {
    "use server";
    const title = data.get("title") as string;
    await cookiesClient.models.Todo.create({
      content: title,
      done: false,
      priority: "medium",
    });
    revalidatePath("/");
  }

  return (
    <>
      <h1>Hello, Amplify 👋</h1>
      {user && <Logout />}
      <form action={addTodo}>
        <input type="text" name="title" />
        <button type="submit">Add Todo</button>
      </form>

      <ul>
        {todos && todos.map((todo) => <li key={todo.id}>{todo.content}</li>)}
      </ul>
    </>
  );
}

export default App;

Terminate dev server

Go to localhost in the browser to make sure you can now log in and create and list to-dos. You can end your development session by shutting down the frontend dev server and cloud sandbox. The sandbox prompts you to delete your backend resources. While you can retain your backend, we recommend deleting all resources so you can start clean again next time.

Deploy and host a fullstack branch

Now that your app is working, let's deploy it to a shared fullstack branch so you can share the project with your team. Amplify offers a fully managed hosting service with CI/CD built in, making it easy to set up production and staging environments with Git branches. In Gen 2, every Git branch in your repository maps 1:1 to a fullstack branch in Amplify.

Create remote Git repository

If you already have your project remotely hosted in a Git repository, you can skip this step. Otherwise, navigate to your preferred Git provider, and add your project to a new repository. Amplify supports GitHub, AWS CodeCommit, GitLab, and Bitbucket.

Connect branch in the Amplify console

1. To get started with Gen 2, log in to the Amplify console and navigate to your preferred AWS Region. (The Amplify console is available in 19 AWS Regions).
2. From the Public Preview banner, choose Try Amplify Gen 2.

3. In the Git provider screen, choose Option 2: Start with an existing app. Connect the repository you just deployed and pick a branch.

4. Review all of your settings to ensure everything is set up correctly. Choose Save and deploy to deploy your web app.

Manage fullstack branch

The new Amplify console gives you a central place to manage your branches, hosting settings, CI/CD builds, and backend resources. Even though you can access backend resources directly from AWS service consoles, the Amplify console offers built-in user and data administration.