Skip to content

Commit 1c79aac

Browse files
kevinoldkevinold
authored
Create fragments for shared Quickstart content (aws-amplify#6743)
* add prerequisites colocated fragment * add create a project fragment * add build a backend fragment * add deploy and host fragment * move fragments to fragments/gen2 per discussion * update fragment imports to be where the fragment is used
1 parent cf24a06 commit 1c79aac

File tree

6 files changed

+335
-627
lines changed

6 files changed

+335
-627
lines changed

‎src/fragments/gen2/quickstart/build-a-backend.mdx‎

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
## Build a backend
2+
3+
Next, we will add data and auth capabilities to the app.
4+
5+
### Add data
6+
7+
Each of the `resource.ts` files is where you _define_ the corresponding backend resource. If you open up the `/amplify/data/resource.ts` file in your text editor, you will see some generated code already there:
8+
9+
```ts showLineNumbers title="amplify/data/resource.ts"
10+
// amplify/data/resource.ts
11+
import { type ClientSchema, a, defineData } from '@aws-amplify/backend';
12+
13+
/*== STEP 1 ===============================================================
14+
The section below creates a Todo database table with a "content" field. Try
15+
adding a new "isDone" field as a boolean. The authorization rules below
16+
specify that owners, authenticated via your Auth resource, can "create",
17+
"read", "update", and "delete" their own records. Public users,
18+
authenticated via an API key, can only "read" records.
19+
=========================================================================*/
20+
const schema = a.schema({
21+
Todo: a
22+
.model({
23+
content: a.string()
24+
})
25+
.authorization([a.allow.owner(), a.allow.public().to(['read'])])
26+
});
27+
28+
export type Schema = ClientSchema<typeof schema>;
29+
30+
export const data = defineData({
31+
schema,
32+
authorizationModes: {
33+
defaultAuthorizationMode: 'apiKey',
34+
// API Key is used for a.allow.public() rules
35+
apiKeyAuthorizationMode: {
36+
expiresInDays: 30
37+
}
38+
}
39+
});
40+
41+
/*== STEP 2 ===============================================================
42+
Go to your frontend source code. From your client-side code, generate a
43+
Data client to make CRUDL requests to your table. (THIS SNIPPET WILL ONLY
44+
WORK IN THE FRONTEND CODE FILE.)
45+
46+
Using JavaScript or Next.js React Server Components, Middleware, Server
47+
Actions, or Pages Router? Review how to generate Data clients for those use
48+
cases: https://docs.amplify.aws/gen2/build-a-backend/data/connect-to-API/
49+
=========================================================================*/
50+
51+
/*
52+
"use client"
53+
import { generateClient } from "aws-amplify/data";
54+
import { type Schema } from "@/amplify/data/resource";
55+
56+
const client = generateClient<Schema>() // use this Data client for CRUDL requests
57+
*/
58+
59+
/*== STEP 3 ===============================================================
60+
Fetch records from the database and use them in your frontend component.
61+
(THIS SNIPPET WILL ONLY WORK IN THE FRONTEND CODE FILE.)
62+
=========================================================================*/
63+
64+
/* For example, in a React component, you can use this snippet in your
65+
function's RETURN statement */
66+
// const { data: todos } = client.models.Todo.list()
67+
68+
// return <ul>{todos.map(todo => <li key={todo.id}>{todo.content}</li>)}</ul>
69+
```
70+
71+
<Accordion title='What is a schema?' eyebrow='Learn more'>
72+
The schema generated by Amplify is for a to-do app. A schema is a blueprint
73+
for how our app's data will be organized. Within the schema, we will define
74+
models which will correspond to a database table—`Todo` in the above code.
75+
Finally, we will define fields which are attributes that each data instance
76+
will have—in the generated code, the fields are `name` and `description`. Each
77+
field will have a type attached to it—in the above examples, we are stating
78+
that both `name` and `description` are strings.
79+
</Accordion>
80+
81+
Let's make a quick change to our data model and add a `done` field. This will be a `boolean`, which can be set to `true` or `false` depending on whether our to-do list item is complete. Let's also add a priority field, which will be an `enum`. This field type will allow for just a few options to be stored—low, medium, or high.
82+
83+
We've removed the default comments to shorten the code below; however, you can choose to keep them for help in connecting to your frontend resources.
84+
85+
```diff title="amplify/data/resource.ts"
86+
// amplify/data/resource.ts
87+
import { type ClientSchema, a, defineData } from '@aws-amplify/backend';
88+
89+
// ...
90+
91+
const schema = a.schema({
92+
Todo: a
93+
.model({
94+
content: a.string(),
95+
+ done: a.boolean(),
96+
+ priority: a.enum(['low', 'medium', 'high'])
97+
})
98+
.authorization([a.allow.owner(), a.allow.public().to(['read'])]),
99+
});
100+
101+
export type Schema = ClientSchema<typeof schema>;
102+
103+
export const data = defineData({
104+
schema,
105+
authorizationModes: {
106+
defaultAuthorizationMode: 'apiKey',
107+
// API Key is used for a.allow.public() rules
108+
apiKeyAuthorizationMode: {
109+
expiresInDays: 30,
110+
},
111+
},
112+
});
113+
114+
// ...
115+
```
116+
117+
Once you save your changes to the data model, your changes will be deployed in seconds within your cloud sandbox.
118+
119+
Our Todo data model also has authorization set up. Our model has the `authorization` method chained to it, which you can add rules to. In our example, we are allowing an owner, or the person who creates the Todo instance, to perform all actions on the data they own. We are also allowing all page viewers, including unauthenticated users, to read data. These can be modified; for example, we could remove the `.to(['read'])` and allow all visitors to perform all actions on data. We could also add permissions for signed-in users or users who belong to user groups such as `Admin`. You can learn more about all options for authorization in the [customize your auth rules](/gen2/build-a-backend/data/customize-authz/) section of the docs.
120+
121+
Let's remove public access.
122+
123+
```js
124+
.authorization([a.allow.owner()]),
125+
```
126+
127+
Then, you will see the `defineData` function, which has our schema and authorization configuration passed in as arguments. We have an `apiKey` set up to enable public access. Let's change our `defaultAuthorizationMode` to `userPool` instead so that the default is to use user authentication.
128+
129+
```js
130+
export const data = defineData({
131+
schema,
132+
authorizationModes: {
133+
defaultAuthorizationMode: 'userPool'
134+
}
135+
});
136+
```
137+
138+
The definitions are imported and set in the `backend` file. We will not need to change anything in this file right now, but you can see its contents, which define a backend with our data and auth configurations from their respective files.
139+
140+
```ts title="amplify/backend.ts"
141+
// amplify/backend.ts
142+
import { defineBackend } from '@aws-amplify/backend';
143+
import { auth } from './auth/resource.js';
144+
import { data } from './data/resource.js';
145+
146+
defineBackend({
147+
auth,
148+
data
149+
});
150+
```
151+
152+
### Add authentication
153+
154+
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, setting the authentication method to log in with email.
155+
156+
```ts title="amplify/auth/resource.ts"
157+
// amplify/auth/resource.ts
158+
import { defineAuth } from '@aws-amplify/backend';
159+
160+
/**
161+
* Define and configure your auth resource
162+
* When used alongside data, it is automatically configured as an auth provider for data
163+
* @see https://docs.amplify.aws/gen2/build-a-backend/auth
164+
*/
165+
export const auth = defineAuth({
166+
loginWith: {
167+
email: true,
168+
// add social providers
169+
externalProviders: {
170+
/**
171+
* first, create your secrets using `amplify sandbox secret`
172+
* then, import `secret` from `@aws-amplify/backend`
173+
* @see https://docs.amplify.aws/gen2/deploy-and-host/sandbox-environments/features/#setting-secrets
174+
*/
175+
// loginWithAmazon: {
176+
// clientId: secret('LOGINWITHAMAZON_CLIENT_ID'),
177+
// clientSecret: secret('LOGINWITHAMAZON_CLIENT_SECRET'),
178+
// }
179+
}
180+
},
181+
/**
182+
* enable multifactor authentication
183+
* @see https://docs.amplify.aws/gen2/build-a-backend/auth/manage-mfa
184+
*/
185+
// multifactor: {
186+
// mode: 'OPTIONAL',
187+
// sms: {
188+
// smsMessage: (code) => `Your verification code is ${code}`,
189+
// },
190+
// },
191+
userAttributes: {
192+
/** request additional attributes for your app's users */
193+
// profilePicture: {
194+
// mutable: true,
195+
// required: false,
196+
// },
197+
}
198+
});
199+
```
200+
201+
Let's customize the verification email for our app. We can add a subject line by defining an object with email authentication properties. Again, we have removed comments for brevity.
202+
203+
```diff title="amplify/auth/resource.ts"
204+
// amplify/auth/resource.ts
205+
import { defineAuth } from '@aws-amplify/backend';
206+
207+
export const auth = defineAuth({
208+
loginWith: {
209+
- email: true,
210+
+ email: {
211+
+ verificationEmailSubject: 'Welcome! Verify your email!'
212+
+ },
213+
// add social providers
214+
externalProviders: {
215+
}
216+
}
217+
});
218+
```

‎src/fragments/gen2/quickstart/create-nextjs-project.mdx‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
## Create a project
2+
3+
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**.
4+
5+
```bash
6+
npm create next-app@14 -- next-amplify-gen2 --typescript --eslint --app --no-src-dir --no-tailwind --import-alias '@/*'
7+
cd next-amplify-gen2
8+
```
9+
10+
The easiest way to get started with AWS Amplify is through npm with `create-amplify`.
11+
12+
```bash
13+
npm create amplify@latest
14+
```
15+
16+
```console
17+
? Where should we create your project? (.) # press enter
18+
```
19+
20+
Running this command will scaffold a lightweight Amplify project in your current project with the following files:
21+
22+
```text
23+
├── amplify/
24+
│ ├── auth/
25+
│ │ └── resource.ts
26+
│ ├── data/
27+
│ │ └── resource.ts
28+
│ ├── backend.ts
29+
│ └── package.json
30+
├── node_modules/
31+
├── .gitignore
32+
├── package-lock.json
33+
├── package.json
34+
└── tsconfig.json
35+
```
36+
37+
## Start local dev server
38+
39+
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.
40+
41+
```bash
42+
npm run dev
43+
```
44+
45+
<Callout info>
46+
47+
Now [configure your AWS account to use Amplify](/gen2/start/account-setup/). Note: If you already have an AWS profile with credentials on your local machine, and you have configured the corresponding AWS profile with the **AmplifyBackendDeployFullAccess** permission policy, you can skip this step.
48+
49+
</Callout>
50+
51+
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:
52+
53+
```bash
54+
npx amplify sandbox
55+
```
56+
<Callout warning>Do not use cloud sandbox environments in production.</Callout>
57+
58+
You should now have these two commands running concurrently in different terminal windows.

‎src/fragments/gen2/quickstart/deploy-and-host.mdx‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
## Deploy and host a fullstack branch
2+
3+
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.
4+
5+
### Create remote Git repository
6+
7+
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](https://docs.github.com/en/get-started/quickstart/create-a-repo), [AWS CodeCommit](https://docs.aws.amazon.com/codecommit/latest/userguide/how-to-create-repository.html), [GitLab](https://docs.gitlab.com/ee/user/project/index.html), and [Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/create-a-git-repository/).
8+
9+
### Connect branch in the Amplify console
10+
11+
1. To get started with Gen 2, log in to the [AWS console](https://console.aws.amazon.com/console/home?#amplify) and navigate to your preferred Region. (The Amplify console is available in [19 Regions](https://docs.aws.amazon.com/general/latest/gr/amplify.html#amplify_region)).
12+
2. If you have never created apps with Amplify before, choose _Create an app_ from the purple banner (top screenshot). If you have Amplify apps, you can find the option under *New app > Build an app (Gen 2)*.
13+
14+
![gen2](/images/gen2/getting-started/console1.png)
15+
16+
3. In the Git provider screen, choose _Option 2: Start with an existing app_. Connect the repository you just deployed and pick a branch.
17+
18+
<Callout warning>Next.js 14 apps require a [minimum node version](https://nextjs.org/blog/next-14#other-changes) of 18.17 at build time.</Callout>
19+
20+
4. Under _Advanced settings_, navigate to _Build Image_ and enter `amplify:al2023`. The Amplify Amazon Linux 2023 build image supports Node.js versions 18 and 20 at build time. You can specify the Node.js version during your build via [live package updates](https://docs.aws.amazon.com/amplify/latest/userguide/custom-build-image.html#setup-live-updates) or [nvm](https://github.com/nvm-sh/nvm). Amplify Hosting will automatically deploy your compute runtime to match the Node.js version used at build time.
21+
22+
![Amplify Gen 2 console showing the "Advanced Settings" view with "amplify:al2023" specified for build image](/images/gen2/getting-started/console4.png)
23+
24+
<Callout warning>If you have an existing Gen 2 application, you can modify the build image by navigating to _Hosting_ -> _Environment Variables_ and create a new environment variable `_CUSTOM_IMAGE` with the value `amplify:al2023`, then redeploy the build.</Callout>
25+
26+
5. Review all of your settings to ensure everything is set up correctly. Choose _Save and deploy_ to deploy your web app.
27+
28+
<video autoPlay={true} muted={true} loop={true} width="100%">
29+
<source src="/images/gen2/getting-started/console1.mp4" />
30+
</video>
31+
32+
33+
### Manage fullstack branch
34+
35+
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.

‎src/fragments/gen2/quickstart/prerequisites.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
## Prerequisites
2+
3+
Before you get started, make sure you have the following installed:
4+
5+
- [Node.js](https://nodejs.org/) v18.17 or later
6+
- [npm](https://www.npmjs.com/) v9 or later
7+
- [git](https://git-scm.com/) v2.14.1 or later
8+
- You will also need to [create an AWS account](https://portal.aws.amazon.com/billing/signup). Note that AWS Amplify is part of the [AWS Free Tier](https://aws.amazon.com/amplify/pricing/).

0 commit comments

Comments
 (0)