Quickstart

👋 Welcome to AWS Amplify! In this quickstart guide, you will:

1. Deploy a React and Vite app
2. Build and connect to a database with real-time data updates
3. Configure authentication and authorization rules

Deploy a fullstack app to AWS

We've created a starter "To-do" application to help get started faster. First, you will create a repository in your GitHub account using our starter React template.

1. Create the repository

Use our starter template to create a repository in your GitHub account. This template scaffolds create-vite-app with Amplify backend capabilities.

Use the form in GitHub to finalize your repo's creation.

2. Deploy the starter app

Now that the repository has been created, deploy it with Amplify.

Select GitHub. After you give Amplify access to your GitHub account via the popup window, pick the repository and main branch to deploy. Make no other changes and click through the flow to Save and deploy.

3. View deployed app

1├── amplify/ # Folder containing your Amplify backend configuration
2│   ├── auth/ # Definition for your auth backend
3│   │   └── resource.tsx
4│   ├── data/ # Definition for your data backend
5│   │   └── resource.ts
6|   ├── backend.ts
7│   └── tsconfig.json
8├── src/ # React UI code
9│   ├── App.tsx # UI code to sync todos in real-time
10│   ├── index.css # Styling for your app
11│   └── main.tsx # Entrypoint of the Amplify client library
12├── package.json
13└── tsconfig.json

When the build completes, visit the newly deployed branch by selecting "View deployed URL". Since the build deployed an API, database, and authentication backend, you will be able to create new to-do items.

In the Amplify console, select the main deployment > Data in the left-hand menu > Data manager to see the data entered in your database.

Make frontend updates

Let's learn how to enhance the app functionality by creating a delete flow for to-do list items.

4. Set up local environment

Now let's set up our local development environment to add features to the frontend. Click on your deployed branch and you will land on the Deployments page which shows you your build history and a list of deployed backend resources.

At the bottom of the page you will see a tab for Deployed backend resources. Click on the tab and then click the Download amplify_outputs.json file button.

Clone the repository locally.

git clone https://github.com/<github-user>/amplify-vite-react-template.git
cd amplify-vite-react-template && npm install

Now move the amplify_outputs.json file you downloaded above to the root of your project.

1├── amplify
2├── src
3├── amplify_outputs.json <== backend outputs file
4├── package.json
5└── tsconfig.json

5. Implement delete functionality

Go to the src/App.tsx file and add in a new deleteTodo functionality and pass function into the <li> element's onClick handler.

1function App() {
2  // ...
3  function deleteTodo(id: string) {
4    client.models.Todo.delete({ id })
5  }
Copy  highlighted code example
6
7  return (
8    <main>
9      <h1>My todos</h1>
10      <button onClick={createTodo}>+ new</button>
11      <ul>
12        {todos.map(todo => <li
13          onClick={() => deleteTodo(todo.id)}
Copy  highlighted code example
14          key={todo.id}>
15          {todo.content}
16        </li>)}
17      </ul>
18      <div>
19        🥳 App successfully hosted. Try creating a new todo.
20        <br />
21        <a href="">Review next step of this tutorial.</a>
22      </div>
23    </main>
24  )
25}

Try out the deletion functionality now by starting the local dev server:

npm run dev

This should start a local dev server at http://localhost:5173.

6. Implement login UI

The starter application already has a pre-configured auth backend defined in the amplify/auth/resource.ts file. We've configured it to support email and password login but you can extend it to support a variety of login mechanisms, including Google, Amazon, Sign In With Apple, and Facebook.

The fastest way to get your login experience up and running is to use our Authenticator UI component. In your src/App.tsx file, import the Authenticator UI component and wrap your <main> element.

1import { Authenticator } from '@aws-amplify/ui-react'
2import '@aws-amplify/ui-react/styles.css'
Copy  highlighted code example
3// ... other imports
4
5function App() {
6  // ...
7  return (
8    <Authenticator>
9      {({ signOut, user }) => (
Copy  highlighted code example
10        <main>
11          {/*...*/}
12          <button onClick={signOut}>Sign out</button>
Copy  highlighted code example
13        </main>
14      )}
15    </Authenticator>
Copy  highlighted code example
16  )
17}

The Authenticator component auto-detects your auth backend settings and renders the correct UI state based on the auth backend's authentication flow.

Try out your application in your localhost environment again. You should be presented with a login experience now.

To get these changes to the cloud, commit them to git and push the changes upstream.

git commit -am "added authenticator"
git push

Amplify automatically deploys the latest version of your app based on your git commits. In just a few minutes, when the application rebuilds, the hosted app will be updated to support the deletion functionality.

Make backend updates

Let's update our backend to implement per-user authorization rules, allowing each user to only access their own to-dos.

7. Set up local AWS credentials

To make backend updates, we are going to require AWS credentials to deploy backend updates from our local machine.

Skip ahead to step 8, if you already have an AWS profile with credentials on your local machine, and your AWS profile has the AmplifyBackendDeployFullAccess permission policy.

Otherwise, set up local AWS credentials that grant Amplify permissions to deploy backend updates from your local machine.

8. Deploy cloud sandbox

To update your backend without affecting the production branch, use Amplify's cloud sandbox. This feature provides a separate backend environment for each developer on a team, ideal for local development and testing.

To start your cloud sandbox, run the following command in a new Terminal window:

npx ampx sandbox

Once the cloud sandbox has been fully deployed (~5 min), you'll see the amplify_outputs.json file updated with connection information to a new isolated authentication and data backend.

9. Implement per-user authorization

The to-do items in the starter are currently shared across all users, but, in most cases, you want data to be isolated on a per-user basis.

To isolate the data on a per-user basis, you can use an "owner-based authorization rule". Let's apply the owner-based authorization rule to your to-do items:

1import { type ClientSchema, a, defineData } from '@aws-amplify/backend';
2
3const schema = a.schema({
4  Todo: a.model({
5    content: a.string(),
6  }).authorization(allow => [allow.owner()]),
Copy  highlighted code example
7});
8
9export type Schema = ClientSchema<typeof schema>;
10
11export const data = defineData({
12  schema,
13  authorizationModes: {
14    // This tells the data client in your app (generateClient())
15    // to sign API requests with the user authentication token.
16    defaultAuthorizationMode: 'userPool',
Copy  highlighted code example
17  },
18});

In the application client code, let's also render the username to distinguish different users once they're logged in. Go to your src/App.tsx file and render the user property.

1// ... imports
2
3function App() {
4  // ...
5  return (
6    <Authenticator>
7      {({ signOut, user }) => (
Copy  highlighted code example
8        <main>
9          <h1>{user?.signInDetails?.loginId}'s todos</h1>
Copy  highlighted code example
10          {/* ... rest of the UI */}
11        </main>
12      )}
13    </Authenticator>
14  )
15}

Now, let's go back to your local application and test out the user isolation of the to-do items.

You will need to sign up new users again because now you're working with the cloud sandbox instead of your production backend.

To get these changes to the cloud, commit them to git and push the changes upstream.

git commit -am "added per-user data isolation"
git push

Once your build completes in the Amplify Console, the main backend will update to support the changes made within the cloud sandbox. The data in the cloud sandbox is fully isolated and won't pollute your production database.

🥳 Success

That's it! You have successfully built a fullstack app on AWS Amplify. If you want to learn more about how to work with Amplify, here's the conceptual guide for how Amplify works.