DEV Community: Michael Liendo

How to Enable Fine-Grained Control Over Your Amplify Projects!

Michael Liendo — Wed, 15 Dec 2021 14:55:26 +0000

Overview

When adding a backend resource with AWS Amplify, like a Cognito User Pool, a Lambda function, or an S3 bucket, we provide reasonable defaults and best practices so that you can spend more time focusing on your business logic.

At Amazon, we like to say we take care of the Undifferentiated Heavy-Lifting ™️.

However, we realize that our users may have specific needs that differ from what we have in place. For example, when adding authentication with amplify add auth, we automatically set the password length to be at least 8 characters long without requiring special characters.

This may not work out for every organization, so we allow users to run amplify update auth to change some of those attributes from right within the Amplify CLI.

This works great, but AWS Services have many knobs that users can tweak and it isn't practical to add every one in our CLI.

To address that, we recently added a new command to the CLI:

amplify override <category>

This command integrates with the AWS CDK to allow your Amplify generated resources to be configured at a much more granular level that is easily reproducible.

In this post, we'll look at examples on how this may be used in your Amplify projects.

Overriding Authentication

During the process of adding authentication with the amplify add auth command, you can enable varying use cases such as adding federated identities from social providers, setting password defaults and more.

But let's say you wanted to do something really specific like changing the length of time a signup-confirmation email is valid for. Amplify defaults to 30 days. But maybe your organization only allows for 2. That's now possible with only a few commands:

amplify override auth

This command integrates with the CDK to create an overrides.ts file that looks like so:

import { AmplifyAuthCognitoStackTemplate } from '@aws-amplify/cli-extensibility-helper';

export function override(resources: AmplifyAuthCognitoStackTemplate) {

}

Inside of the override function, we have access to the resources parameter to reference everything pertaining to our authentication resource. Since this file is written in TypeScript, we can take advantage of intellisense to find the TemporaryPasswordValidityDays option that we need:

🗒️ Notice how there is not only information about the property, but a link to learn more.

Here is the complete example:

import { AmplifyAuthCognitoStackTemplate } from '@aws-amplify/cli-extensibility-helper';

export function override(resources: AmplifyAuthCognitoStackTemplate) {
    resources.userPool.policies = {
        passwordPolicy: {
      ...resources.userPool.policies["passwordPolicy"], // spread in all other policy values
            temporaryPasswordValidityDays: 2,
        },
    }
}

Modifying a DynamoDB Table Created By AppSync

AWS AppSync is a managed GraphQL service that is used to build production-ready, real-time applications.

Amplify takes this a step further by adding directives that make working with AppSync even easier.

One such directive is @model. Adding this to a type will tell Amplify to not only add a DyanamoDB table with the same name, but to prompt is the user would like to automatically have all CRUDL operations scaffolded out as well as websocket subscriptions 🤯

When working with AppSync in Amplify, we abstract away the database so that focus is put on the data model itself. However by running the following command, you can gain access and modify it:

amplify override api

Imagine a scenario where you'd like to not only enable a TTL on your database, but also take advantage of the new DynamoDB Standard-IA table class released at re:Invent this year.

🗒️ A Time To Live (TTL) specifies the time when an item is to be deleted in a database. For more information and an example walkthrough, checkout this post

These are the steps we'd use to accomplish that:

Run amplify add api and follow the prompts.
- change the auth mode from API to Amazon Cognito User Pool.
- Select the Todo (Single Object with Fields) schema template.
Once the schema opens up in the editor, paste in the below code:

type Todo @model @auth(rules: [{ allow: owner }]) {
    id: ID!
    name: String!
    description: String
    ttl: Int!
}

Run amplify override api to create an overrides.ts file for this resource category.
In this file, paste in the following code:

import { AmplifyApiGraphQlResourceStackTemplate } from '@aws-amplify/cli-extensibility-helper'

export function override(resources: AmplifyApiGraphQlResourceStackTemplate) {
    resources.models['Todo'].modelDDBTable.timeToLiveSpecification = {
        enabled: true,
        attributeName: 'ttl', //what we defined in our schema
    }

    resources.models['Todo'].modelDDBTable.addPropertyOverride(
        'TableClass',
        'STANDARD_INFREQUENT_ACCESS'
    )
}

That's it! 🎉

Notice how we can dive into our API to access the underlying database to set the TTL. Also, notice how we can use the addPropertyOverride feature of the CDK to change the table class since Standard-IA tables are so new, the option isn't typed out in the CDK as of this writing. 😎

Viewing the AWS Console, we can verify our overrides.

Conclusion

In this post we looked at 3 different ways an Amplify generated resource can be overridden:

At the top-level, as shown in overriding authentication.
By diving into the category to override underlying resources, as shown with TTL.
By diving deep to use the CDK to modify the resource at the CloudFormation level, as shown with addPropertyOverride.

At the time of this writing, auth, storage, and api are all able to be overridden, with function being the next to be added.

If wanting to create your own resources within Amplify, you may want to check out my last post where I showed how to do just that!

Thanks for following along, and I can't wait to see what you all have to build! If you have any questions feel free to drop a comment and follow me on Twitter to stay up to date with what I have going on!

The Complete Guide to Adding AWS Resources to Your Amplify Project

Michael Liendo — Mon, 13 Dec 2021 18:03:24 +0000

During Dr. Werner Vogel's re:Invent keynote, the point was made that AWS has a ton of services--each one designed to solve a customer pain point.

AWS Amplify composes some of those services together to create a framework designed for today's professional frontend developer. These services can be added with a CLI command. For example, to add a GraphQL API or REST API, one would type.

amplify add api

We at Amplify integrate core services needed to build production apps, but the reality is that today's applications need a wide variety of services. One initial solution, was to put all 175+ services in the CLI 😅

I'm happy to say we have a better way:

amplify add custom

This command will scaffold out files using AWS Cloud Development Kit (CDK) or AWS CloudFormation. You can then use this stack to add whatever services you like. In this post, we'll walk through what that experience is like so you can feel comfortable adding any AWS resource to your next project, not just the ones offered directly through the CLI .

Adding a custom resource

As mentioned, both CDK and CloudFormation are supported, but my opinion is that most frontend developers will enjoy writing TypeScript to generate their infrastructure, so that's what we'll be using in this post.

After running amplify add custom and following the prompts, Amplify will generate our CDK stack.

If you've worked in CDK with TypeScript before, you should feel right at home since the generated files are very similar to what you would get when running

cdk init --template sample-app --language typescript

The key differences is that we include a few more examples for folks to get started, and a few Amplify helpers to easily connect Amplify with your CDK backend.

After deleting the commented examples for now, the following screenshot is what is left:

Adding an SNS Topic and SQS

Let's say you wanted to send a text message to a group of interested individuals. To avoid bottling up the downstream service, we'll also add an SQS Queue so messages can be picked up in batches.

This scenario is exactly what we provide out of the box as one of our commented out examples!

Keep in mind that any resource that you see in the CDK docs is fair game to be added.

Understanding Amplify helpers

Now that we understand how resources can be added, let's look at some of the extra benefits Amplify provides.

AmplifyHelpers: We automatically install a package called @aws-amplify/cli-extensibility-helper.

This currently contains two methods: getProjectInfo and addResourceDependency. We'll chat about adding resources dependencies in a bit, but let's first explore the available project info.

Calling this method currently provides two properties: envName and projectName.

The envName corresponds to the current Amplify environment. By default, this is dev, though by running amplify env add <envName> users can add branches to their backends , much like when working in git.

🚨Due to the lifecycle of when the environment name gets populated, the envName here is to be used for conditional checks only, not for naming resources:

if(AmplifyHelpers.getProjectInfo().envName === 'prod') {
  // create an IAM role to allow access to a prod account
}

Additionally, the projectName is the name specified in the CLI when first running amplify add custom (see the first screenshot). As we saw when we created our resources, this is great for project organization:

🗒️Note that the above screenshot also shows the correct way to pull in the Amplify environment when naming resources.

Working with Amplify generated resources

In addition to AmplifyHelpers.getProjectInfo(), let's look at AmplifyHelpers.addResourceDependency().

This method will bring in resources that we generated with the Amplify CLI.

🗒️ It's worth noting that when running amplify add custom, example 3 of the commented boilerplate code provides this function by default.

Because we're in TypeScript, our retVal variable is already typed to reference our Amplify resources:

If by chance you just pushed up some resources and aren't seeing values like Arn and region, running amplify build will regenerate this file.

Within the addResourceDependency function, we can specify which of our Amplify resources we would like access to by passing in an array, where each object in it has a category and resourceName key.

Keep in mind that what we have so far is a type representation of what we need (int, string, etc). So from here, we can use a CDK helper method to extract the actual value:

const authArn = cdk.Fn.ref(retVal.auth.amplifystripestarter9420c337.UserPoolArn)

Accessing custom stacks in Lambda

To look at the other side of the fence, suppose we ran amplify push and deployed our custom stack. Then we add a Lambda via amplify add function to our project. In this case, we also need to grant access for our Lambda to call SNS.

To accomplish this, we can take advantage of the custom-policies.json file that we now generate with every Lambda created:

[
    {
        "Action": ["SNS:Publish"],
        "Resource": ["arn:aws:sns:*:*:mySNSTopic-${env}"]
    }
]

Note that we support wildcards for the region and account number. Additionally, we interpolate the Amplify environment by using the ${env} syntax.

Conclusion

In this example, we took a peek at how to subscribe an SQS Queue to an SNS Topic, but the learnings went far beyond that. By adding custom resources with the CDK, pulling in existing resources created with the Amplify CLI, and updating policies so Lambda functions have permissions to call our external resources, users now have the ability to create truly rich applications while minimizing time spent in the AWS Console.

This is just one of aspects of Amplify's new extensibility releases. For a rundown of all the new enhancements and a glimpse into the posts I'll be releasing, checkout my blog post over on A Cloud Guru that covers 5 new Amplify features to take your app to any scale.

Combining NextJS, AWS Amplify and Stripe to build a catering app (part 1)

Michael Liendo — Thu, 28 Oct 2021 15:19:26 +0000

When prototyping out complex applications that contain lots of moving parts, many developers choose AWS Amplify for both hosting and development. However, as we've seen with many customers already, Amplify is great for production setups as well. While there may be reasons to extend beyond what Amplify provides, in this series of posts, I'll showcase much of Amplify's capabilities by building out a serverless Catering application.

Project Overview

I chose this project because it's practical enough to explore many parts of AWS, yet digestible enough to fit in a short series of posts.

This project will have many moving pieces. To name a few:

NextJS: Our React framework of choice. We'll use this framework to sell our products.
Stripe: To handle payment processing and secure compliance, we'll integrate with a 3rd party to do the heavy lifting
React Native (Expo): A cross-platform mobile app framework. Delivery drivers will need to share their location and interact with our cloud backend.
AppSync: A managed GraphQL service that has in-built support for web sockets.
Amazon Location Service: Allows us to setup geofences, maps, track drivers, and send out a notification when a driver is close to a customer's home.
AWS Amplify: An infrastructure-as-code solution aimed at professional frontend developers. We'll use the Amplify CLI, Amplify libraries, and Amplify hosting in this project.

Architecture Overview

The architecture diagram at the top of this page shows a full flow that we'll create in these first few posts. However, for this particular post, we'll tackle the following subset:

Essentially, when a user visits our app's homepage, we'll fetch the products from our Stripe Dashboard by calling a REST endpoint. When a user clicks on a product, we'll post those details to create a checkout session for the user to pay.

If the payment is successful, we'll trigger a webhook that will let us run some customer logic. In our case, that will be to automatically create a user for our app. That newly created user can then view their order details.

Creating our products

We'll start our journey in the Stripe Dashboard, specifically, on the Create New Products page. I'm not going to walk through setting up an account in this post, but once on the dashboard, make sure you are in test mode.

From the products page, go ahead and create a few one-time products.

Before creating our API to fetch those products, we'll go to the Stripe Dashboard to grab our secret keys. Jot those down, or keep the tab open. We'll be needing these shortly.

Adding our dependencies

As mentioned, we'll be using NextJS to create a page for our customers to buy our catering packages. To get started with this, we'll create a new NextJS app.

npx create-next-app catering-with-amplify

Once inside our project directory, we'll add a few needed dependencies:

npm i aws-amplify @aws-amplify/ui-react @stripe/stripe-js

aws-amplify: Let's our frontend integrate with the backend we're about to create
@aws-amplify/ui-react: Pre-built UI components
@stripe/stripe-js: Allows us to redirect our customers to a checkout session.

Initializing our backend

🗒️ This project series uses version 6.3.1 of the Amplify CLI. Run npm i -g @aws-amplify/cli to bring in the latest version.

While our users need a frontend to view the products and checkout, most of our time is going to be spend setting up our backend.

To start, we'll run the following command in our terminal:

amplify init

This will prompt a series of questions after detecting our application. When asked to accept the default configuration, say No.

While most of the defaults are safe to accept, there are a few areas we'll change since we are using NextJS:

* What is the name of the source directory: [enter a period here]
* What is the name of the build directory: [enter .next here]

After that, select the AWS Profile you'd like to use.

🎉 We're now ready to begin adding our AWS Services

Adding our backend services

Adding Authentication

The first service to add is our authentication session. This sets up Amazon Cognito so that our users can login after they've completed an order.

amplify add auth

- Accept the default configuration
- Select **Email** as the sign in method
- Select "No, I am done."

✅ That was easy!

The next service is the bulk of this post

Adding a REST API

In a lot of frameworks, creating an API is done by adding a file that then becomes an API route. While this is great for speed of development and simplifies the process, the tradeoff is that there is less control on what that function can be attached to. For now, we want our function to serve as an API route, later on, we'll explore how a serverless function can be triggered automatically, when someone signs up.

Amplify supports this flexibility via its CLI. To get started, run the following command:

amplify add api

- Select REST
- **Give this a friendly name like "cateringapi"**
- Provide a path: `/catering`
- Create a new Lambda function
- Name the function `cateringfunc`
- NodeJS as the environment
- Select **Serverless ExpressJS function** as the template
- Select `y` for advanced settings
- Select `N` for all options **except** for configuring secret values, select `y`
- For the key of the secret, type `STRIPE_SECRET_KEY`
- For the value, grab the **secret key** (not the publishable key) from the Stripe Dashboard (make sure you're in **test mode**) and enter it.
- I'm done
- Select the option to edit the local lambda function now

The file should open up in your editor. Take a moment to look over what was generated. A couple of highlights:

The comments at the top show to get retrieve the secret value we created

const { Parameters } = await (new aws.SSM())
  .getParameters({
    Names: ["STRIPE_SECRET_KEY"].map(secretName => process.env[secretName]),
    WithDecryption: true,
  })
  .promise();

Parameters will be of the form { Name: 'secretName', Value: 'secretValue', ... }[]

All of our CRUD routes have been generated for us based on the /catering path we provided

Now that we had a chance to admire the generated code, go ahead and delete everything in this file! (Really!)

Adding business logic

Adding imports

Below are the imports we'll need. The only additional one here is the stripe package. We'll add that shortly.

const express = require('express')
const bodyParser = require('body-parser')
const awsServerlessExpressMiddleware = require('aws-serverless-express/middleware')
const Stripe = require('stripe')
const app = express()
const aws = require('aws-sdk')

Helpers methods and middleware

Next up, we'll want to create a method to grab our secret key. This snippet essentially wraps the original code to do so.

const fetchStripeSecret = async () => {
    const { Parameters } = await new aws.SSM()
        .getParameters({
            Names: ['STRIPE_SECRET_KEY'].map((secretName) => process.env[secretName]),
            WithDecryption: true,
        })
        .promise()

    return Parameters[0].Value
}

Our template is based on ExpressJS a nodeJS framework meant to run on a server. In Express, middleware is a core concept.

The following automatically converts our payload to JSON, lets us run express in a serverless function, allows CORS (so we can access our API on the frontend), and finally, attaches our stripe secret to our request so we don't have to add it to every API path.

app.use(bodyParser.json())
app.use(awsServerlessExpressMiddleware.eventContext())

// Enable CORS for all methods
app.use(function (req, res, next) {
    res.header('Access-Control-Allow-Origin', '*')
    res.header('Access-Control-Allow-Headers', '*')
    next()
})

app.use(async (req, _, next) => {
    req.stripeSecretKey = await fetchStripeSecret()
    next()
})

Adding logic to our API paths

From here, we get to define our routes! The generated code prefixed our paths with /catering, but that doesn't mean we can't modify them. The below code allows us to fetch the products we created from Stripe and returns them to our frontend.

/****************************
 * get method to access stripe products *
 ****************************/

app.get('/catering/products', async function (req, res) {
    const stripe = new Stripe(req.stripeSecretKey)

    const productPriceData = await stripe.prices.list({
        expand: ['data.product'],
    })

    const productData = productPriceData.data.map(
        ({ product, unit_amount, id }) => ({
            name: product.name,
            description: product.description,
            price: unit_amount / 100,
            image: product.images[0],
            priceId: id,
        })
    )

    res.json(productData)
})

The following happens whenever a user clicks one of our Stripe products from the frontend. They send us a priceId and a fulfillmentDate, and we handle creating a checkout session and sending that session to the frontend so they can be redirected.

🗒️ Note that in the success_url and the cancel_url, there is an expectation that those respective pages are created: /order/success and /order/canceled. We'll create those in just a bit.

app.post('/catering/checkout-sessions', async (req, res) => {
    const stripe = new Stripe(req.stripeSecretKey)

    try {
        // Create Checkout Sessions from body params.
        const session = await stripe.checkout.sessions.create({
            line_items: [
                {
                    price: req.body.priceId,
                    quantity: 1,
                },
            ],
            payment_method_types: ['card'],
            mode: 'payment',
            success_url: `${req.headers.origin}/order/success?session_id={CHECKOUT_SESSION_ID}`,
            cancel_url: `${req.headers.origin}/order/canceled`,
            metadata: {
                fulfillmentDate: req.body.fulfillmentDate, //new Date().toISOString()
            },
            shipping_address_collection: {
                allowed_countries: ['US'],
            },
        })

        res.status(200).json(session)
    } catch (err) {
        console.log(err)
        res.status(err.statusCode || 500).json(err.message)
    }
})

Our last route is more of an extra. In the next post, we'll store orders in a database, but for now, we'll provide a way for when an order is completed, a customerSessionId is sent to the frontend. We'll send that to this route so it's possible to see the customer details later on.

app.get('/catering/checkout-sessions/:customerSessionId', async (req, res) => {
    const stripe = new Stripe(req.stripeSecretKey)

    const id = req.params.customerSessionId

    try {
        if (!id.startsWith('cs_')) {
            throw Error('Incorrect CheckoutSession ID.')
        }
        const checkoutSession = await stripe.checkout.sessions.retrieve(id)
        console.log(
            'the custoemr session',
            JSON.stringify(checkoutSession, null, 2)
        )
        res.json(checkoutSession)
    } catch (err) {
        res.status(404).json({ statusCode: 404, message: err.message })
    }
})

The last line of code for this file is just to export what we created:

module.exports = app

Recall, we have to install the stripe package for our function.

While in the root of your project, run the following command in your terminal:

cd amplify/backend/function/cateringfunc/src && npm i stripe && cd ../../../../..

That'll go into the functions directory, install the stripe package, and then go back to the home directory.

Before we push up our backend and configure our frontend, we still have a few more options to answer in our terminal. It should currently be in a Press enter to continue state.

Hit enter and select the following options:

Restrict API access **N**
Do you want to add another path **N**

Once that is done, let's save our changes and push up our backend to AWS by running the following command:

amplify push -y

🗒️ amplify push will show us the changes in our backend and ask if we would like to proceed. Adding the -y flag will automatically accept.

While our backend is being pushed up, let's switch over to our frontend

Scaffolding our frontend

😅 I'm going to be honest here, I was going to add a CSS framework, but figured if anyone wanted to use this project they would likely use their own styles. So I kept styling simple and focused on the code. The final version however uses ChakraUI to style 😎

As with every Amplify project, we'll need to tie together our frontend with our backend. Since we are using NextJS, we'll do that by updating our _app.js file to look like the following:

import '../styles/globals.css'
import Amplify from 'aws-amplify'
import config from '../aws-exports'

Amplify.configure(config)

function MyApp({ Component, pageProps }) {
    return <Component {...pageProps} />
}

export default MyApp

Afterwards, we'll add a file called getStripe.js at the root of our project. This file ensures that we use the same instance of Stripe and only load it once.

import { loadStripe } from '@stripe/stripe-js'

let stripePromise = null
const getStripe = () => {
    if (!stripePromise) {
        stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY)
    }
    return stripePromise
}

export default getStripe

Note that the getStripe file makes use of an environment variable. The value for that key can be found on the Stripe Dashboard as the publishable key.

Copy the value from there and in the root of your project create a file called .env.local.

Paste in the following (replacing the value with your actual publishable key):

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY= YOUR_PUBLISHABLE_KEY_STARTS_WITH_PK

Creating our homepage

Our homepage is our first chance to verify our API is setup. Recall that it holds two responsibilities:

Fetching our products
Creating a checkout session once a user has picked a product

Replace what's in pages/index.js with the following:

import { useEffect, useState } from 'react'
import getStripe from '../getStripe'
import { API } from 'aws-amplify'

const Home = () => {
    const [products, setProducts] = useState([])

    useEffect(() => {
        API.get('cateringapi', '/catering/products').then((productData) =>
            setProducts(productData)
        )
    }, [])

    const handleProductClick = async (priceId) => {
        const stripe = await getStripe()
        const data = await API.post('cateringapi', '/catering/checkout-sessions', {
            body: { priceId, fulfillmentDate: new Date().toISOString() },
        })

        await stripe.redirectToCheckout({ sessionId: data.id })
    }

    return <main>view products</main>
}

export default Home

While discussing how react works is outside of this series, the two important parts are the useEffect(), which fetches our products once after the initial load, and the handleProductClick function that creates the checkout session.

Both of those functions make use of our API by using an API Name, Path Name flow. This is why it was important to provide a friendly name for these services in the CLI.

Feel free to style your products however you like, if just wanting to follow along, you can replace to the view products text with the following:

{products.map((product) => {
  return (
    <article
        style={{
          border: '1px solid black',
          margin: '20px',
          display: 'flex',
        }}
        key={product.priceId}
        onClick={() => handleProductClick(product.priceId)}
    >
        <div>
          <img
            src={product.image}
            alt={product.description}
            width="300px"
            height="300px"
          />
        </div>
        <div>
            <h2>{product.name}</h2>
            <h2>
              {new Intl.NumberFormat('en-US', {
                  style: 'currency',
                  currency: 'USD',
              }).format(product.price)}
            </h2>
            <p>{product.description}</p>
        </div>
    </article>
  )
})}

Before testing out our flow, recall that when a customer is transferred over to Stripe to submit a payment, they'll be transferred back to a success page when the payment succeeds, and a cancellation page if the customer backs out of paying.

In the pages directory, create the following pages:

success.js
canceled.js
customer-session/[orderId].js (we'll revisit this one later)

For the cancellation page, we'll keep it super simple and just check the query parameters sent back to see if a user got their by Stripe:

import React, { useEffect } from 'react'

function OrderCancelPage() {
    useEffect(() => {
        const query = new URLSearchParams(window.location.search)

        if (query.get('canceled')) {
            console.log(
                'Order canceled -- continue to shop around and checkout when you’re ready.'
            )
        }
    }, [])
    return <div>Order Cancel Page</div>
}

export default OrderCancelPage

The success page will be very similar, except we'll also give them the ability to view their order by visiting the customer-session/{orderId} page.

import React, { useEffect, useState } from 'react'
import Link from 'next/link'
function OrderSuccessPage() {
    const [orderId, setOrderId] = useState('')
    useEffect(() => {
        // Check to see if this is a redirect back from Checkout
        const query = new URLSearchParams(window.location.search)

        if (query.get('session_id')) {
            setOrderId(query.get('session_id'))
        }
    }, [])

    return (
        <div>
            <h1>Order Success Page</h1>
            <Link href={`/customer-session/${orderId}`}>
                <a>View Order</a>
            </Link>
        </div>
    )
}

export default OrderSuccessPage

For the customer order page, add the following few lines:

import React from 'react'
import { withAuthenticator } from '@aws-amplify/ui-react'

function CustomerOrder() {
    return <div>Protected customer order page.</div>
}

export default withAuthenticator(CustomerOrder)

This page is protected, meaning it needs a user to have an account in order to view it. We'll dive deeper into what that means in just a moment, but for now, let's test out our flow!

Start the app

npm run dev

Visit localhost:3000. Your products should display and upon clicking a product, you should be taken to a Stripe checkout session.

🗒️ In order for a payment to go through, you must enter a sequence of 42 for the card information.

After the payment has gone through, make sure you are taken to the success page. Feel free to also press the Stripe back button to make sure you get to the canceled page.

Going the extra mile

We've done a lot so far. What we have currently can easily be turned into a decent starter project👀

But for this post, we're going to go a bit further. Specifically, when a customer purchases a product, we'll automatically create an account for them to view their order.

Our frontend is already setup to handle this flow:

When a user is taken to the success page, they can click a link to view their order. That will redirect them to the pages/customer-session/{orderId} page where we can pull in our customer details.

Because that's already taken care of, we'll instead focus on our backend.

Creating a Stripe webhook

Creating a webhook is two-fold: We first have to register our endpoint with Stripe, then we have to create the logic for it in our API.

To get started hooking into when a checkout payment has been completed, we'll first hop into our aws-exports.js file to grab our API endpoint.

This file contains all of our secrets and is rightfully automatically added to our .gitignore. Grab the endpoint value from the aws_cloud_logic_custom array:

With the endpoint, we'll once again head to the Stripe Dashboard to create a new webhook: https://dashboard.stripe.com/test/webhooks/create

🚨Make sure to add /payment-webhook to the end of the API endpoint.

After entering in the details, click the + selected events button.

Select the checkout.session.completed event and click add events.

With our webhook created, we'll need to grab the signing secret.

🚨This is not the secret in the top-right of the Dashboard.

Copy the secret to your clipboard.

Creating a webhook endpoint

This part has a lot of similarities to our first routes. We'll start by adding a new path to our existing API via the CLI.

amplify update api

From here, we'll select the following options:

- REST
- cateringapi
- Add another path
- /payment-webhook
- Create a new Lambda function
- cateringwebhookfunc
- NodeJS
- Serverless ExpressJS function

When asked if wanting to configure advanced settings, select y and select the following options:

- Access other resources: y
- Press spacebar on auth and hit enter
- Press spacebar on create and read and hit enter
- Select 'n' for recurring schedule, lambda layers, and environment variables
- Select 'y' for wanting to configure environment secrets

For a secret name, enter STRIPE_SECRET_WEBHOOK. For the value, enter the copied webhook signing secret from the Stripe Dashboard.

When asked what you'd like to do, say Add a secret.

For a secret name, enter STRIPE_SECRET_KEY. For the value, enter the secret key value from the homepage of the Stripe Dashboard: https://dashboard.stripe.com/test/dashboard

🗒️ We've already entered this secret key for our first function. However, there isn't currently a way to share secrets between functions. Fortunately, the team is already working to make this a possibility soon!

Select I'm done, and n to wanting to edit the local function now.

For restricting API access select n and also n for adding another path.

🤔 "We just created a function that can create and read users from our user pool, why aren't we restricting access to it?" Excellent question! Instead of using IAM permissions to lock down the API path, we are using the Stripe webhook secret. We'll check the request headers to make sure it matches the webhook secret we stored on AWS.

Adding our endpoint logic

In our code editor, we'll navigate to amplify/backend/function/paymentwebhookfunc/src/app.js

As before, Amplify does a great job at providing sample code. Note that since we allowed create and read access to our Cognito pool, we are shown the environment variable we can use to access it.

/* Amplify Params - DO NOT EDIT
    AUTH_AMPLIFYEXAMPLE20C9CA19_USERPOOLID
    ENV
    REGION
Amplify Params - DO NOT EDIT */

Automatically creating users

In our app.js file, we imported a function called createCognitoUser. When it's called, we pass both the userpool ID and the customer's email address.

Let's create this file (in the same directory as app.js) and add our business logic.

The code in here will be relatively straightforward. Using the userpool ID and the customer's email, we first try to create a new user. If that fails, we check to see if it failed because that user already exists. In either attempt, we either return the user or throw an error.

const aws = require('aws-sdk')

const cognito = new aws.CognitoIdentityServiceProvider({
    apiVersion: '2016-04-18',
})

const createCognitoUser = async ({ UserPoolId, Username }) => {
    try {
        const user = await cognito
            .adminCreateUser({
                UserPoolId,
                Username,
                DesiredDeliveryMediums: ['EMAIL'],
                UserAttributes: [
                    {
                        Name: 'email',
                        Value: Username, //email they used to pay
                    },
                ],
            })
            .promise()

        return user
    } catch (e) {
        //check if user already exists
        if (e.code === 'UsernameExistsException') {
            const user = await cognito
                .adminGetUser({
                    UserPoolId,
                    Username,
                })
                .promise()

            return user
        }

        throw Error('application error', e)
    }
}
module.exports.createCognitoUser = createCognitoUser

🗒️ Recall that when we first added authentication, we said our users will sign in via their email. That's why we are using the email value as their username.

Now when a user gets signed up, they will receive an email with a temporary password, and when they try to sign in with that password, they will automatically be prompted to change it to something else, asked if they want to confirm it, and be taken to a protected page!

Testing out our application

Before we try this out, there are a few things we have to make sure we account for.

If you haven't already, make sure you install the stripe package for this function to use. Even though it is part of the same API, it's still a function that has its own set of node_modules.

cd amplify/backend/function/cateringwebhookfunc/src && npm i stripe && cd ../../../../..

This relates to when we entered a duplicate secret key earlier. Currently, Amplify only tries to find secret keys for the first function that gets created. We can workaround this by extending the permissions our webhook function has:

In the src folder of our paymentwebhookfunc directory, there is a file called custom-policies.json.

Open this file and paste in the following:

[
    {
        "Action": ["ssm:GetParameters"],
        "Resource": ["arn:aws:ssm:YOUR_REGION:YOUR_AWS_ACT_NUMBER:*"]
    }
]

If you're unsure about your region, it's the aws_project_region value in your aws-exports.js file.

For the account number however, you'll have to log into the AWS Console and grab it from the top-right portion.

If you know how to grab it, go ahead and do your thing, if not, follow along:

In your terminal, run amplify console and select Amplify Console

After signing in, you'll find your account number in the top-right dropdown.

🗒️ Again, this is just temporary, once support for credentials improves, I'll remove this portion of the post.

With that done, let's run amplify push -y to sync our local changes with the cloud.

Testing our flow

Make sure your app is running on localhost:3000

npm run dev

Buy a product as before, when the purchase succeeds, you should be taken to the success page.

Check your email for a signup confirmation that contains a temporary password.

Back in your app, click the link to view your order and use your email and temporary password to login.

From here, you should be prompted to change your password, and optionally, verify your email.

🎉Once that is all done, you're directed to the order page🎉

Extra Credit Challenge

As mentioned in the beginning, functions don't need to be attached to an API. For example, Cognito allows us to attach them to authentication events.

Since users already have to provide an email to pay, having them also verify that email may seem like an unnecessary step. It'd be great if after a user signs up, but before they are confirmed, we automatically verify their email!

By running amplify update auth you can do just that!

Below are the CLI options to get to the trigger:

And here is a link to a code snippet to auto-verify emails

This is part 1 of a many-part series!

In this post, we created a REST API and allowed our app to accept Stripe payments. We also added a secure webhook to automatically create users for our application. Once a user has been created, they can signin to view their order details.

This is still just scratching the surface.

Next, we'll go deep on how we can combine Expo, Amazon Location Service, and AWS AppSync to deliver a realtime geo delivery app that can respond to geo updates and order status changes!

If you have any comments, suggestions or ideas on what you'd like to see implemented, feel free to leave a comment and let me know!

Fetch both price and product data from stripe in a single api call

Michael Liendo — Tue, 19 Oct 2021 06:52:04 +0000

Use Case

I want to display products in my web app that show the product's name, description and price. Similar to the below screenshot

I want to use the Stripe Dashboard as my source-of-truth.
Upon visiting my simple store, I would like my customers to receive the latest product information.

The Problem

I tried to fetch all the product data, but that didn't work since it doesn't contain the prices for those products.

I tried to fetch the price data, but the product field only contains an ID for the product and not the rest of the data.

🤔 "Do I really have to get all of my price data, then iterate over each price just to get the product data?"

Neither the Stripe Price docs or the Product docs address this use case. A quick google search confirmed my initial approach:

But for such a common task, it just wasn't sitting right with me.

// Detect dark theme var iframe = document.getElementById('tweet-1450200714664349699-935'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1450200714664349699&theme=dark" }

The Solution

Special shoutout goes to my buddy Nick (@dayhaysoos). He let me know that prices can use the expand parameter to get the corresponding product information.

After a quick search through the Stripe docs for "expand", the solution became clear:

import Stripe from 'stripe'

const Home = ({ productPriceData }) => {
    console.log({ productPriceData })

    return <div>display stripe data</div>
}

export async function getServerSideProps() {
    const stripe = new Stripe(process.env.STRIPE_SECRET_KEY)

    const productPriceData = await stripe.prices.list({
        expand: ['data.product'], // 🎉 Give me the product data too
    })
    console.log(JSON.stringify(productPriceData, null, 2))

    return {
        props: { productPriceData },
    }
}

export default Home

🗒️ Quick Notes

Expand can be used for just about any API call, but will only go 4 levels deep on what it returns.
It's showcased here, but just to be clear, you can dig into an object with dot-notation: data.product.nestedKey.nestedKey2
I was going to use the revalidate key in getStaticProps to be cool, but then I realized that if a user refreshes the page, they should always see the correct price.

Sending SMS Messages with AWS Amplify and NextJS

Michael Liendo — Fri, 15 Oct 2021 06:30:47 +0000

Send an SMS to Customers Using React and AWS Amplify

Whether it's notifying customers that their food is ready, getting school notifications, or a status update on a delivered package, SMS is a great way to get a communicate.

When it comes to sending push notifications, email, or SMS, AWS has a service known as Amazon Simple Notification Service or SNS. In this post, we'll discuss how we can leverage SNS inside of a project built with React and AWS Amplify.

Specifically, we'll mimic a scenario often found in delivery apps, such as catering companies: Customers have sent us orders, and now that the order is ready, we'll send a notification that the order is out for delivery. The architecture setup is a bit contrived, but this post will contain plenty of foundational tools for folks to get started with and will help us build more complex apps in the future.

Key SNS Concepts

When working with SNS, it's important to define four main ideas you'll commonly run into:

Topic: It's possible to create many instances of the SNS service. You can for example, create on that sends emails regarding signups, and another that sends texts regarding orders. Each SNS instance has a name, which AWS calls a "topic".
Publisher: Simply put, who is sending the message. In our example, we'll create an API to publish the message ourselves. However, this can also be triggered based on another action, such as an item being saved to a database.
Subscriber: Converse to a publisher is a subscriber. Who are the recipients.
Fan Out: One of the most common design patterns in serverless architectures. This allows multiple endpoints (emails, phone numbers, etc) to subscribe to a single topic. In doing so, when a single message is published, it can be sent (or fanned out) to multiple targets.

Project Starter Files

To keep the focus on sending SMS messages to our customers, our project will use a static list of orders. To get started with this setup, feel free to clone this repo from GitHub and install the dependencies.

Upon starting the project, you should see the following page on localhost:3000

The markup to create the application isn't the focus, but feel free to take a look. The mock data used for an order is definitely something worth calling out. In particular, note that an order is made up of an id, products, status, and customerNotes.

🤔 Because this is a delivery app, you might be wondering why there aren't fields like phoneNumber and address. Instead of having those accessible on the frontend, we'll use the order's id to send them to the driver from our backend whenever an order is ready for delivery. This helps protect sensitive customer information by only allowing drivers to access them when they need them.

Adding Our Backend

Recall our scenario: A driver is given a list of customer orders. When selecting an order, we want to notify the customer that their order is being delivered.

To get started, we'll want to first setup Amplify so we can begin adding categories.

If needing to setup AWS Amplify for the first time, add run the command npm i -g @aws-amplify/cli and follow the prompts after running amplify configure.

In your terminal and while in your project's directory, run the following command to initialize Amplify in your project:

amplify init

After selecting a name for the project, select n when asked if wanting to accept the default configuration.

The default configuration assumes a project created with create-react-app, but this project is scaffolded with create-next-app.

While most of the defaults will be the same, when asked for a Source Directory Path, instead of src, use .

Also, when asked for a Distribution Directory Path, instead of build, use .next

Once done initializing our project with Amplify, we'll install two packages:

aws-amplify: This will allow us to connect our frontend to our cloud backend
@aws-amplify/ui-react: Prebuilt UI components so we don't have to write our own login and signup forms

npm i aws-amplify @aws-amplify/ui-react

Authentication

One of the greatest features of Amplify, is its ability to easily add authentication.

This allows developers to focus more on their apps business logic and less on unvarying app aspects. In the case of our application, we want to provide our drivers the ability to login. In our terminal, we'll run the following command:

amplify add auth

This will walk us through a series of prompts. In this project, we'll accept the default configuration and have drivers signup with a username.

Adding an API

This is the main part of the project!

From here, we'll create an API that instructs a serverless function to send an SMS message.

Using the Amplify CLI again in our terminal, we'll run the following command:

amplify add api

As before, this will ask a series of prompts on how we would like to configure our API.
Amplify supports both GraphQL and REST API's, and both can be configured in the same project. For our purposes, we'll create a REST API and select the options in the screenshot below:

🚨We'll update the code for the Lambda function that was created for us in the next step, but keep the terminal prompt open as there are a few more prompts to answer.

For the Lambda that was just templated for us, let's replace the generated code with the following:

/* Amplify Params - DO NOT EDIT
    API_DELIVERYAPI_APIID
    API_DELIVERYAPI_APINAME
    ENV
    REGION
Amplify Params - DO NOT EDIT */ const AWS = require('aws-sdk')
const SNSClient = new AWS.SNS()

exports.handler = async (event) => {
    // 1. get orderID from the event
    const orderID = JSON.parse(event.body).orderID

    // 🪄 used orderID to look up orderDetails in database 🪄

    const order = {
        orderID: '123-abc',
        address: '987 fakeaddress ln',
        phoneNumber: '+12813308004', //replace with your phone #
    }

    let response

    try {
        // 2.  🎉 send order update to customer
        const resp = await SNSClient.publish({
            Message: 'Your order is out for delivery',
            TargetArn: process.env.SNS_TOPIC_ARN,
            MessageAttributes: {
                sms: {
                    DataType: 'String.Array',
                    StringValue: JSON.stringify([order.phoneNumber]),
                },
            },
        }).promise()
        console.log(resp)
        // 3. send response back to the frontend
        response = {
            statusCode: 200,
            headers: {
                'Access-Control-Allow-Origin': '*',
                'Access-Control-Allow-Headers': '*',
            },
            body: JSON.stringify({
                address: '987 fakeaddress ln',
            }),
        }
    } catch (e) {
        console.log(e)
        // todo: update response for when things go bad 😢
    }
    return response
}

Aside from bringing in the aws-sdk itself to create an new SNS instance, there are 3 key areas we'll want to focus on (I noted the code snippets above to reflect the 3 areas).

The data from the frontend is sent as a string and is accessible from the body of the event. By parsing it out, we can use that to lookup the order from a database.
Here, we send the message! This showcases how easy it is to publish a message. We specify the SNS topic we want to send to, specify a message, and provide some attributes. The attributes are important here. By default, SNS will publish a message to all of its subscribers. This allows us to specify the exact subscriber(s) to send to. More on that last bit in a minute!
We allow CORS access and send the address to the driver on the frontend.

🗒️ Because the purpose of this post is to showcase how to send an SMS message, we're removing topics like database lookups or updating database fields.

With our Lambda function coded out, back in your terminal, finish the prompts by answering the remaining questions as show in the screenshot below.

Creating Our SNS Topic

In our Lambda function, you'll notice that there is an environment variable for the target ARN:

TargetArn: process.env.SNS_TOPIC_ARN

This assumes that we have an SNS topic already configured. Amplify doesn't have a CLI command to create SNS topics, but we can do so in the console and the use the CLI to handle the rest.

Head to this link to be taken to the AWS Console for SNS, note you may be promoted to sign into your AWS account.

🗒️ Ensure the region in the top right of the page is the same as the region your Amplify project is in.

From here, select "Standard" as the topic type, and give it a name. Once done, click the "Create topic" button at the bottom on the page.

The next step is to create a subscriber. This can be done automatically through the API or manually via the Console. While we're in the Console we'll select "Create Subscriber" and on the following page, enter our subscriber details

🚨Copy the ARN. We'll need that in a bit. Also note that the phone number entered, should be replaced with a valid phone number and is what should be put in the order object inside of our Lambda function.

You may be wondering what is going on with the filter policy. When publishing to an SNS topic, the message will automatically be fanned out to all of the subscribers. By specifying a filter policy on the subscriber, we are telling SNS that this subscriber only cares about messages with those attributes. Note that these attributes match up with what is in lambda function:

await SNSClient.publish({
            Message: 'Your order is out for delivery',
            TargetArn: process.env.SNS_TOPIC_ARN,
            MessageAttributes: {
                sms: {
                    DataType: 'String.Array',
                    StringValue: JSON.stringify([order.phoneNumber]),
                },
            },
        }).promise()

With our topic created with a subscriber, we can head back to our code.

Updating Our Function

As mentioned, you'll want to update the phone number in our Lambda function to be the same as the phone number entered in your SNS topic.

Next, we'll update need to give our Lambda function permission to call SNS, and also set the environment variable for the SNS_TOPIC_ARN.

To update the Lambda permissions, Amplify now creates a file called custom-policies.json whenever a lambda function is created.

Replace the contents of that file with the following JSON policy, replacing the ARN with the ARN of your SNS topic:

[
  {
    "Action": ["sns:Publish"],
    "Resource": ["arn:aws:sns:us-east-1:ActNumber:Orders"] 
  }
]

That's all it takes to give our function permission to call SNS.

To add the environment variable, we'll use the CLI. Run the following command in your terminal:

amplify update function

Select the Lambda function we are working with and follow the prompts to add an environment variable as show in the screenshot below:

With that, our Lambda function is now configured to send messages to subscribers!

Go ahead and push up all of local backend services to AWS by running the following command:

amplify push -y

Testing Our Application

With our backend changes up, let's create a test user and configure our frontend to trigger an API call.

In _app.js, uncomment the code so that we can our frontend can be configured with the credentials needed to talk to our backend.

Next, we'll do the same in index.js. Note that in addition to the import and export statements, there is the onClick handler definition and where it's being called that need to be uncommented.

With everything saved, go ahead and restart the application, sign up for an account, and upon clicking a product, the phone number used to subscribe should receive a message!

🚨 To clean up the app, run amplify delete. This will delete all of the Amplify created resources, both locally and in the cloud. Note that since the SNS topic was created outside of Amplify, that would have to be done manually.

While a bit contrived, this example showcased how to use Amplify to send updates to SNS subscribers and a practical use case for using filter policies. In a real world application, a database entry could serve as a trigger for the Lambda instead of an API call. If interested in how to setup a database trigger, feel free to checkout my post on Setting Up A Serverless Contact Form.

Thanks for checking out this post, let me know your thoughts down in the comments and stay tuned for more tips on how Amplify can speed up your development flow!

Create a Resume Uploader Using AWS Amplify

Michael Liendo — Thu, 08 Jul 2021 04:09:53 +0000

In the first part of this series, we learned how to send emails by creating a contact form. In this post, we'll take things up a notch by also allowing our users to upload attachments.

Sites like Indeed.com allow for job seekers to upload their resumes with the idea that employers can browse those resumes to see if a candidate is a good fit.

The scope of this post will be catered to job seekers submitting resumes, but it can also be extended to account for companies as well.

📝 Because the knowledge in this series builds with each post, in this post, we'll spend more time focusing on the how and only touch on the why when appropriate.

Getting Started

We'll kick things off by downloading the starter project. This will contain our UI, but it currently has no backend logic tied to it.

👉🏽 Grab the starter files here

Once the project is cloned to our machine, we'll make sure we're on the resume-uploader-starter branch. From here, we can install the dependencies and run our application.

When running the application, we should be presented with the following screen:

// screenshot of app

This is nearly identical to the last project, however, when clicking the "upload resume" button there is a new option to upload a file:

The goal of this project is to allow a user to upload a file, and have it both saved in AWS as well as emailed to a verified recipient.

Understanding Our Backend

Before diving into the code, let's take a moment to walk through how our AWS services will be working together.

Using the above screenshot as a guide, as a candidate enters our application, they will be asked to sign up.

📝 We want users to authenticate to not only restrict who can upload/download files, but also in case resumes have the same name ie. resume.pdf. So we'll use their generated user ID as a prefix to their resume.

Getting Started

In our terminal, we'll make sure we're in the project's root directory. For here, we'll install some Amplify dependencies as well as initialize our project to use the Amplify CLI:

npm i aws-amplify @aws-amplify/ui-react && amplify init

Once the dependencies are done installing, there will be a prompt asking us how we would like our app configured.

Enter a name of your choosing, then **select n **when asked if you would like to initialize amplify with the default configuration.

This is because we want to change the build directory from build to out since NextJS will be building our site as static HTML files.

Hit enter to accept the default options when prompted, but when asked for a "Distribution Directory Path" type out and hit enter.

When done, confirm the profile you'd like to use. The entire flow should look similar to the following screenshot:

📝 If you ever accidentally accept the default configuration or want to change it later, typing the command amplify configure project will take you back to the prompt.

With our project configured, let's started adding our services.

Adding Authentication

Amazon Cognito user pools will store our users while identity pools will manage their permissions. Amplify can set this up for us with reasonable defaults (password protection, TOTP, etc) all from the CLI.

To get started, we'll type the following command in our terminal:

amplify add auth

The prompts will ask us how we would like to configure Amazon Cognito.

For our use case, we'll make the following selections:

Default Configuration
Username
No, I am done.

The entire flow, should look like the following screenshot:

With auth templated through the CLI, let's move on to our next service.

Adding An API

Setting up an API using AWS AppSync will be very similar to the last section, with the addition of a reference to the candidate's resume.

Back in the terminal, type the following command:

amplify add api

For the prompts that follow, select the following options:

GraphQL
[enter] to select the default name
Amazon Cognito User Pool
No, I am done.
No
Single object with fields
Yes

The generated flow, should look like the following screenshot:

Selecting "Yes" to the last option should've opened up our schema file in our editor.

Replace the contents with the following:

type Candidate 
  @model 
  @auth(rules: [{ allow: owner, operations: [create, update] }]) {
    id: ID!
    name: String!
    email: String!
    resumeFile: String!
    userIdentity: String!
}

As mentioned in the last post, the @model directive will automatically create our DynamoDB table and the corresponding CRUDL operations to interact with it.

The @auth directive says that the only operations allowed on this API are the ability to create and update. Furthermore, those operations are scoped to the currently signed in user.

The fields correspond to what is being stored in our database -- id, name, email, and resumeFile.

We also have a userIdentity field. When a user is added to Cognito, a user ID is created for them. We are adding this to our API so that our lambda function (as well as employers in the future) will be able to access resumes. Note that this ID is not associated with our user's usernames or passwords 😉

The next two services are where things really start to get interesting. Let's dive in!

Adding An S3 Bucket

In our application, we are choosing to store resumes in Amazon Simple Storage Service (S3). Doing so has the following benefits:

Decreases the payload size of what we're storing in our database
We don't have to mess around with sending multi-part form data to our lambda
We have a dedicated space where emails are sent, as opposed to just an email inbox

Much like the other services thus far, we'll create our S3 bucket from within the CLI.

To start, we'll type the following command in out terminal:

amplify add storage

📝 Amplify comes with two primary types of storage: A database, and an S3 bucket.

Through the prompts, we'll configure our S3 bucket by selecting the following options:

Content
[enter] to accept the default
[enter] to accept the default
Auth users only
use the spacebar to select all options
No

When done, the generated output should look like the following screenshot:

With S3 configured, it's time to tie our services together!

Adding A Lambda Function

Our lambda function has the following requirements:

Is triggered by the dynamoDB table associated with our API
Has access to the S3 bucket we just created
Has permission to send email with SES

Amplify gives us the ability to accomplish all of this without heading to the AWS Console.

To get started, type the following command in the CLI:

amplify add function

From here, make the following selections:

Lambda function
"resumeFunc"
NodeJS
Lambda Trigger
Amazon DynamoDB Stream
Use API category graphql @model table
Configure Advanced Settings? Yes
"Y" to access other resources
[use spacebar to select storage]
[use spacebar to select our S3 bucket]
select "read"
"N" to not invoking on a recurring schedule
"N" to not enable lambda layers
"Y" to configuring environment variables
SES_EMAIL
[enter an email address you have access to]
"I'm done"
"N" we don't need to configure secret values
"Y" we want to edit the local function now

📝 If you think that was a lot of steps, try doing it manually!

📝 Once done, the CLI should provide you with a few environment variables that it generated: ENV, REGION, and _YOUR_BUCKET_. Keep track of the bucket variable for now as we'll be needing that later.

Similar to the last post, this function will be triggered whenever there is a change event on our database (when an item is inserted, modified, or deleted).

Also worth re-mentioning from the last post is that under heavy load, DynamoDB with batch changes together. This is why we are iterating over event.Records.

Replace the generated code in the lambda function with the following:

const aws = require('aws-sdk')
const nodemailer = require('nodemailer')

const ses = new aws.SES()
const s3 = new aws.S3()
const transporter = nodemailer.createTransport({
  SES: { ses, aws },
})

exports.handler = async (event) => {
  for (const streamedItem of event.Records) {
    if (streamedItem.eventName === 'INSERT') {
      //pull off items from stream
      const filename = streamedItem.dynamodb.NewImage.resumeFile.S
      const candidateEmail = streamedItem.dynamodb.NewImage.email.S
      const candidateName = streamedItem.dynamodb.NewImage.name.S
      const candidateIdentity = streamedItem.dynamodb.NewImage.userIdentity.S
      //change this to match your bucket name👇🏽
      const RESUME_BUCKET = process.env.STORAGE_RESUMEBUCKET_BUCKETNAME 
      try {
        //get record from s3
        const resumeFile = await s3
          .getObject({
            Bucket: RESUME_BUCKET,
            Key: `protected/${candidateIdentity}/${filename}`,
          })
          .promise()

        //setup email with attachment
        const mailOptions = {
          from: process.env.SES_EMAIL,
          subject: 'Candidate Resume Submission',
          html: `<p>You can reach ${candidateName} at the following email: <b>${candidateEmail}</b></p>`,
          to: process.env.SES_EMAIL,
          attachments: [
            {
              filename,
              content: resumeFile.Body,
            },
          ],
        }

        //send email
        await transporter.sendMail(mailOptions)
      } catch (e) {
        console.error('Error', e)
      }
    }
  }
  return { status: 'done' }
}

The code above can be split into four basic sections:

Configure our project: Here we're bringing in and setting up relevant packages. The nodemailer package is a handy utility we'll install in a bit. This makes sending emails with attachments a bit simpler.
Grabbing the data we need from the event
Getting the relevant resume file. Note that our files are protected.
Setting up our email and sending the email with an attachment.

The last thing to do here is give our function permission to call SES.

In the last section, we set up SES. Feel free to grab the ARN from that resource, or follow the steps in that post to setup SES for the first time.

📝 If you have the AWS CLI installed, you can actually setup an email by typing the following command in your terminal and clicking the verification link sent to the provided email address:

aws ses verify-email-identity --email-address your-email@emai.com --region us-east-1 --profile=your-aws-profile

Once you have an ARN for the SES email we created, we'll want to open up our function's cloudformation template:

//from the root of your project
cd amplify/backend/function/YOUR_FUNC_NAME

From there, open the file ending in -cloudformation-template.json.

Add a statement to the lambdaexecutionpolicy object:

{
"Effect": "Allow",
"Action": "ses:SendRawEmail",
"Resource": "YOUR_SES_ARN"
}

The lambdaexecutionpolicy should look like the following screenshot:

Finally, we'll change into the src directory of our lambda function and install the nodemailer package:

// assuming we're still in the amplify/backend/function/ourFunction directory:

cd src && npm i nodemailer

📝 We don't have to install the aws-sdk unless we're testing our function locally. AWS already installs this package in the lambda runtime.

Configure Our Application

With all of our services configured and connected, it's time to push them up to AWS.

In the root of our application, we'll run the following command:

amplify push

This will bring up a table, showing all of our configured services. When asked if we'd like to continue, select yes (Y) and accept all of the default options.

☕️ This will deploy our backend resources to the cloud, generate code for our API, and create an aws-exports file containing our backend secrets (automatically added to .gitignore).

Configuring Our Frontend

With our backend successfully deployed, we can now connect it to our frontend.

In _app.js add the following snippet to connect our frontend to our Amplify backend:

import Amplify from '@aws-amplify/core'
import config from '../src/aws-exports'
Amplify.configure(config)

The next step is to have our users sign in. In addition to letting our users have their own account, user sign in gives us the following benefits:

We have insight into who is storing information in our S3 bucket
We can control who has access to view and upload items in S3

Amplify comes with several ways to add authentication to our applications depending on how much control we'd like to have over the process.

For this project, we'll go with the simplest, which is a higher-ordered-function that fully manages the authentication flow.

In index.js modify the top portion to look like the following snippet:

import { AppHeader } from '../components/AppHeader'
import { withAuthenticator } from '@aws-amplify/ui-react'

function HomePage() {
  return (
    <>
      <AppContainer>
        <AppHeader />
        <ResumeModal />
      </AppContainer>
    </>
  )
}

export default withAuthenticator(HomePage)

//rest of code...

The last step is to add the actual code that sends data from our frontend to both our database and to S3.

In ResumeForm.js add the following import statements:

import { API, Storage, Auth } from 'aws-amplify'
import { createCandidate } from '../src/graphql/mutations'
Storage.configure({ level: 'protected' })

The API module will talk to AppSync, the Storage module will talk to S3 and we are bringing in our createCandidate mutation that was generated automatically when we pushed up our schema.

Note that we are setting the configuration level to protected.

The S3 module comes with three modes:

public: All files are stored at the same level. Accessible to all users.
protected: Files are separated by the user's Cognito identity ID. Anyone can read, but only the user can write.
private: Only accessible to the given user.

📝 In some cases, it might make sense for files to be public. What's important to remember is that files with the same name will overwrite one another, which would be bad in our application. Example: user1 uploads resume.pdf, user2 uploads resume.pdf. For that reason we use protected.

The last bit before we test this out is to add the code that actually does the uploading. In the same file, there is a function called handleResumeFormSubmit.

Let's replace the comment and console statement with the following:

const currentCredentials = await Auth.currentCredentials()
const fileKey = await Storage.put(
  formState.resumeFile.name,
  formState.resumeFile
)
const response = await API.graphql({
  query: createCandidate,
  variables: {
    input: {
      name,
      email,
      resumeFile: fileKey.key,
      userIdentity: currentCredentials.identityId,
    },
  },
})

📝 Because we configured S3 as protected, it will automatically prepend our files with protected/{COGNITO_IDENTITY_ID}/, however, we call Auth.currentCredentials() to get the Cognito User Identity ID to send to our lambda function.

After making sure all our files are saved, restarting the application and signing up for an account, we should be able to upload a .pdf and have it sent to the email we verified with SES! 🎉

Conclusion

I'll be frank--it took a lot longer to explain this process, than it did to actually do it 😅

The level of power that AWS Amplify provides lies in its suite of tools. In this post we took a deep dive into its CLI. However, out of the box, it provides a CI/CD pipeline, UI components, an Admin UI, and much more.

Thank you for taking the time to read this! Let me know your thoughts and questions in the comments, or follow me on Twitter for more insights into AWS Amplify!

Until next time 🤖

Serverless Contact Form Using AWS Amplify

Michael Liendo — Tue, 06 Jul 2021 16:20:02 +0000

When building out applications, sending email is a frequently needed feature. In addition, it's likely that the data sent in the email needs to be stored in a database for record keeping, analytics, or additional processing.

AWS provides a range of services that help make setting up an API, database, and email transport quick, and secure. Specifically, AWS Amplify provides a lot of the functionality we'll need out of the box, and Amazon SES will send emails on our behalf.

Overview of Services

AWS Amplify is a suite of services ranging from UI components and a use case focused CLI to a CI/CD console and backend-scaffolding GUI.

On the other hand, Amazon SES provides a scalable solution for sending email and is used at companies like Reddit and Netflix.

In this post, we'll be using the Amplify CLI along with its JavaScript libraries to create a backend for a contact form, and use Amazon SES to send that information to our email.

Getting Started

If you don't already have an AWS account or have the Amplify CLI installed, follow this guide.

🚨 This project makes use of lambda environment variables. The ability to do this via the CLI was introduced in version 5.1.0. You may need to run npm install -g @aws-amplify/cli to ensure you're on the latest version.

Once setup, clone this contact-form-starter branch from this github url.

After cloning the project, install the dependencies and run the project. Below are some helpful commands:



// visit: https://github.com/mtliendo/amplify-email-recipes/tree/contact-form-starter

git clone git@github.com:mtliendo/amplify-email-recipes.git
cd amplify-email-recipes
git checkout contact-form-starter
npm install
npm run dev

Once the project has started, visit localhost:3000 and you should be presented with the following screen:

Understanding Our Backend

Using the above image as a reference, the Amplify services we'll need for our backend are in the following order:

AppSync: Fully managed GraphQL API
DynamoDB: NoSQL database
Lambda: FaaS/cloud function

In short, when a user fills out their contact form, that information will be stored in our database via our API. When that item is successfully saved, it will automatically trigger a function to send an email.

Sounds like a lot. Let's see what we have to do to get this working.

Initializing Our Backend 🚀

We'll start creating our backend by opening up a terminal and making sure we're in the root directory of our project.

From here, we'll initialize Amplify by running the following command:



amplify init

We'll give our project a name and when prompted, select n to deny the default configuration. This is because we will be deploying our application as a static site. In NextJS, the name of that build directory is called out.

In the terminal, accept all of the prompts, except when it comes to the Distribution Directory Path enter out.

The entire flow should look like the below screenshot:

Lastly, after selecting AWS profile we'll choose the profile we'd like to use.

The flow should look similar to the following screenshot:

Adding An API

With our application ready to use the Amplify CLI, we'll create our backend. As mentioned earlier, we are using AWS AppSync, which is a managed GraphQL API.

Traditionally, when sending email, a REST API is used. However, I've found that as needs change, AppSync provides more flexibility when it comes to handling authorization and a few other features.

To add an API in Amplify, we'll simply type the following command in our project's terminal:



amplify add api

While in the CLI prompts, choose the following options:

GraphQL
[enter] to accept the default name
API key
"Contact form public API"
[enter] to accept a default of 7 days
[enter] to accept "No, I am done."
[enter] to accept the default "N" option
[enter] for a Single object with fields
"y" to edit the schema now
Select your editor of choice

By selecting those options through the prompts, we told Amplify how we would like our API to be built.

At this point, Amplify has opened up a file called schema.graphql with a sample Todo object. Replace everything in that file with the following:



type Candidate 
  @model 
  @auth(rules: [{ allow: public, operations: [create] }]) {
   id: ID!
   name: String!
   email: AWSEmail!
}

To break down what's happening here, we are first creating a type called Candidate. In our application, a Candidate represents the user submitting their information.

The @model text is called a directive. When Amplify sees this, it will automatically create a DynamoDB table and create CRUDL operations for the type it's associated with (in this case, Candidate).

The @auth directive setups up authorization rules on our API. Here we are saying, "We want our API to be public to anyone with an API key, but we only want them to be able to create entries in out database, they can't read, update, or delete items.

The next few lines are the fields associated with a Candidate. Here it's required that every Candidate has a unique id (automatically created with ID), a name, and an email -- AWS has a primitive called AWSEmail that automatically validates an email pattern.

With that, our API and database are ready to be deployed. Before doing so, let's move on to our function.

Setting Up Our Function Trigger

AWS Lambda is an event-driven function. Meaning, it is called as a response to something. Often times, this is an endpoint like /pets, but in our application, we want this function to be called whenever an item is added to our database.

Fortunately, Amplify takes care of this process by allowing us to set this up from the CLI.

In our terminal, let's go through the following prompts:

amplify add function
Lambda function (serverless function)
"contactformuploader" as the name of the function
NodeJS
Lambda Trigger
Amazon DynamoDB Stream
Use API category graphql @model backed DynamoDB table in the current Amplify project
[enter] to not configure advanced settings
[enter] to edit the local function now
Choose your editor of choice

This will open up the function in your editor. Before we remove the contents, let's chat about the generated code.

When a change happens to a record in our database -- a change being either a INSERT, MODIFY, or REMOVE event, that information is sent as a stream of data to our lambda function.

However, our database can undergo heavy traffic. So instead of firing our lambda for one change at a time, the changes can be sent in batches called shards. No need to get too technical, but this is why the generated code is iterating over event.Records.

To drive the concept home, here's a diagram to showcase streaming and sharding:

With that mini-lesson out of the way, let's replace the content in our lambda function, with the following:



const aws = require('aws-sdk')
const ses = new aws.SES()

exports.handler = async (event) => {
  for (const streamedItem of event.Records) {
    if (streamedItem.eventName === 'INSERT') {
      //pull off items from stream
      const candidateName = streamedItem.dynamodb.NewImage.name.S
      const candidateEmail = streamedItem.dynamodb.NewImage.email.S

      await ses
          .sendEmail({
            Destination: {
              ToAddresses: [process.env.SES_EMAIL],
            },
            Source: process.env.SES_EMAIL,
            Message: {
              Subject: { Data: 'Candidate Submission' },
              Body: {
                Text: { Data: `My name is ${candidateName}. You can reach me at ${candidateEmail}` },
              },
            },
          })
          .promise()
    }
  }
  return { status: 'done' }
}

This function will be automatically called when a candidate submits their information. The event will contain the related stream of data. So from here our job is simple:

Grab the items from the stream, and send an email.

Using the AWS SDK, we call the sendEmail function from the ses module.

Wit that out of the way, we now have at least touched on all the pieces of our backend. We still however have a couple loose ends.

Our function doesn't have permission to interact with SES
We need to setup this process.env.SES_EMAIL variable
We've yet to setup SES
Our frontend code isn't setup to interact with our backend.

Let's change gears for a bit and start with the third item and revisit the others.

Setting Up SES

As mentioned earlier, Amazon Simple Email Service (SES) provides a scalable way to send email. When first setting up SES, AWS will place you in sandbox mode.

This means we'll have the following constraints:

We can only send/receive to verified email addresses
We can only send 1 email/sec
Only 200 emails/day are allowed

Fortunately for our application, this won't matter too much.

To get started, let's hop into our terminal and run the following command:



amplify console

When prompted, select "Amplify console".

📝 you may be asked to log in to your AWS account

Once logged in, search for "SES" in the top search bar of the console and hit enter.

You should see a view similar to the one above. If not, you may need to click the top banner to be taken to this newer UI.

From here, perform the following steps:

Click the orange "Create identity" button
Select the "Email address" option and enter your desired email
Click the orange "Create identity" button

That's it! Setting up an email for this service is well...simple 😅

There are two things we'll need before we hop back into our code.

First, copy the ARN for your email by clicking the copy icon on the verified identities screen as show in the screenshot below:

Store that in a notepad. We'll need it in a bit.

Next, SES sent a confirmation email to the email address that was provided. Click the verification link and we're all set to head back to our code.

Updating Our Lambda

Recall that we need to both give our function permission to access SES, and add an environment variable to the function called SES_EMAIL.

Let's first update the permissions.

In your project directory we'll want to navigate to the following directory:



amplify/backend/function/your-function-name/

Inside of this directory, you'll see the src directory for lambda, and a file titled



your-function-name-cloudformation-template.json

Select this file.

No need to be intimidated, this JSON code is known as Cloudformation and is what Amplify has been creating for us when we were interacting with the CLI.

It's full of settings and rules and we're about to add one more.

Search for lambdaexecutionpolicy (it should be right around line 132).

This object has a Statement array that currently contains a single object. This object lets our function create logs in AWS.

Add the following object to the Statement array and save:



{
 "Action": ["ses:SendEmail"],
 "Effect": "Allow",
 "Resource": "the-arn-you-copied-from-ses"
}

This small addition gives our function the ability to call the sendEmail function using the email we verified.

The lambdaexecutionpolicy object should look like the below screenshot (note I removed my email in place of a * for a bit more flexibility):

The next step is to add the environment variable to our function.

Back in the terminal, run the following command:



amplify update function

Enter the following options:

Lambda function (serverless function)
[Select your function name]
Environment variables configuration
type SES_EMAIL
Enter the email that was verified with SES
I'm done
No -- I don't want to edit the local file now

Push Up Our Backend

We've done a lot by only running a few commands in the CLI. This templated our resources, but we have yet to push everything up to AWS.

Let's fix that by running the following command in the terminal:



amplify push

This will provide a table of the primary resources we created (recall that our database is a secondary resource created by the @model directive).

After selecting that you'd like to continue, select the following options:

Yes -- generate code for the API 🔥
JavaScript
[enter] to allow the default file path
Yes -- generate all possible operations (recall we only allow create per our schema)
[enter] to accept a max depth of 2

It'll take a few minutes for our terminal to finish up, but once that's done, our backend is complete 🎉

Let's wrap this up by giving our frontend the ability to talk to our backend.

Configuring Amplify Libraries

We'll start off by installing the AWS Amplify JavaScript package:



npm i aws-amplify

Once that is installed, we'll marry our frontend and backend together. In _app.js, add the following lines:



import Amplify from '@aws-amplify/core'
import config from '../src/aws-exports'
Amplify.configure(config)

Here we bring in the Amplify library, bring in our config (Amplify generated this and put it in .gitignore), and then we pass in our config to Amplify.

Next up, in ContactForm.js, we'll also bring in the following imports:



import { API } from 'aws-amplify'
import { createCandidate } from '../src/graphql/mutations'

📝 Feel free to check out the createCandidate mutations file that Amplify generated for us.

The API category is how we will talk to our AppSync API. Recall that this should not only store the contact in our database, but send an email to our verified address as well.

The ContactForm.js file has the following lines of code:



// TODO: Add code to send email here
console.log('<send to backend here>')

Replace the above with this snippet:



await API.graphql({
  query: createCandidate,
  variables: {
    input: {
      name,
      email,
    },
  },
})

With that bit out of the way, we can now test our project!

Restart your application on localhost:3000 and test it out. If all went well, after a few seconds you'll have an email in your inbox 🎉

📝 Because our emails are being sent via SES, they may show up in a spam folder or flagged by your email provider. This is because we haven't setup DKIM with SES. Though not terribly difficult, it's out of scope for this tutorial. However, if interested, you can read more about it here

Hosting Our Project

Having this run locally is great, but for a contact form, chances are we want it to be live on the internet.

Fortunately, Amplify allows us to do this from the CLI as well.

To get started, in our terminal, we'll run the following command:



amplify add hosting

From the prompts, we'll select the following options:

Hosting with Amplify Console
Manual Deployment

Once selected, we can run the following command to view changes and upon accepting, our application will be deployed and a live on the web:



amplify publish

Copy and paste the generated URL in your terminal to browser to view.

As you may have noticed in the CLI prompts, Amplify also supports git-based deployments. More information on setting that up can be found in the Amplify docs

Recap

Using Amplify takes care of a lot of the heavy-lifting when it comes to setting up AWS services so that we can focus on our actual business logic.

It's also good to remember that Amplify allows us to own the code that we deploy by letting us modify the generated Cloudformation templates.

Be sure to follow this series, or follow me on Twitter to get notified when the next iteration of this series comes out:

Sending emails with attachments! 📧

Until then 🤖

Building Connect4: Adding Logic

Michael Liendo — Mon, 24 May 2021 14:00:59 +0000

In the second part of this series, we’ll add in the logic that allows two users to play the game locally.

If you’d like to see how we got the project scaffolded and styled, definitely checkout the first part to get a better understanding.

Also, if you'd like to play the final version of what we're building today, click here to do just that!

Developing our mental model

Before we start writing some code, it’s important to get a mental model of how our game data is moving across our files.

Here are some important concepts to keep in mind before a player makes their move:

1) Our game board is an array made up six inner arrays. Each array represents a row on our Connect4 board.



board: [
    [null, null, null, null, null, null, null],
    [null, null, null, null, null, null, null],
    [null, null, null, null, null, null, null],
    [null, null, null, null, null, null, null],
    [null, null, null, null, null, null, null],
    [null, null, null, null, null, null, null],
  ]

2) Inside each of those arrays are 7 null values by default. These represent the areas players can place their tokens. We use the indexes of the null values (from 0-6) to specify a column.



// Connect4.js
// iterate over each array to create a Row

<tbody>
  {gameState.board.map((row, i) => (
     <Row key={i} row={row} play={play} />
   ))}
</tbody>



//Row.js
// row ex) [null, null, null, null, null, null, null, null]
// iterate over each column, cell= the value, i = column index
<tr>
 {row.map((cell, i) => (
   <Cell key={i} value={cell} columnIndex={i} play={play} />
 ))}
</tr>

3) Each token area (Cell) has an event listener attached to it. So when a cell is clicked, we know both its column, and the value inside of it. We can then call the play function we passed from Connect4 -> Row -> Cell.



//Row.js (inside Cell component)
onClick={() => {
  play(columnIndex)
}}

🤔 You might be wondering how we know what row a user clicked in if all a Cell knows is the column and its value (what if someone clicks the very top row when the game just started?) We'll see the logic later on, but because we're working in a grid, we'll just use a for-loop to check the bottom row and work our way up until we find the first available cell in that column.

Adding our logic

The play function that is defined in Connect4.js is going to be our star player in this project. It will be automatically called when a player clicks any cell and is only told what column to place a token in.

So let's start there.

Creating a fresh board

Inside the play function, add the following line:



let board = deepCloneBoard(gameState.board)

As a refresher, when passing JavaScript primitive types around, we pass the actual value:



let a = 2
let b = a
a = 3
console.log(b) // 2

but when passing complex types like objects and arrays, we pass a reference to the original type:



let arr1 = ['hi']
let arr2 = arr1
arr1.push('bye')
console.log(arr2) // ['hi', 'bye']

Sometimes, that behavior is what we want...most times it's not. So to copy the values over, without worrying about pass by value vs pass by reference, we'll crate a utility function that takes in our board and safely returns a copy.

Create a new file called gameUtils.js and add the following code:



//connect4/gameUtils.js
export const deepCloneBoard = (board) => [
  [...board[0]],
  [...board[1]],
  [...board[2]],
  [...board[3]],
  [...board[4]],
  [...board[5]],
]

Here we're immediately returning an array and in row inner array, we are using the spread-operator to copy the values of the board at a given index.

With this function exported, don't forget to import it in Connect4.js by adding the following line:



import { deepCloneBoard } from '../gameUtils'

Adding a player to a board

Back in our Connect4.js file, we'll handle a user being able to place their token in a given column. I explained above how this works conceptually, so after we deep clone our board, add the following code:



//check if cell is taken by starting at the bottom row (5) and working up
//if a cell is null, add the current player (1 or 2) to it.
for (let r = 5; r >= 0; r--) {
  if (!board[r][c]) {
    board[r][c] = gameState.currentPlayer
    break
   }
}

🗒️ At this point, you should be able to run the app and click on a cell to place a red token from the bottom up...but it won't. That's because we are never updating our state to reflect the added player.

As a next step, we'll work between our gameReducer function and our play function so that our application updates when a player places a token.

Working with game state

In our Connect4.js file, at the top of our Connect4 component, there is this line:



const [gameState, dispatchGameState] = useReducer(
 gameReducer,
 initialGameState
)

The useReducer function is a react hook that takes in two arguments: a function that contains the ways our state can update, and a value (initalGameState) that defines what the state looks like by default.

In return, we are given back an array with two fields: What our state looks like currently (gameState) and a function to update our state (dispatchGameState).

Let's fill out our reducer to account for the various ways a game can be updated:



const gameReducer = (state, action) => {
//1
  switch (action.type) {
//2
    case 'newGame':
      return {
        ...initialGameState,
        board: action.board,
      }
//3
    case 'togglePlayer':
      return {
        ...state,
        currentPlayer: action.nextPlayer,
        board: action.board,
      }
//4
    case 'endGame':
      return {
        ...state,
        gameOver: true,
        message: action.message,
        board: action.board,
      }
//5
    case 'updateMessage':
      return {
        ...state,
        message: action.message,
      }
//6
    default:
      throw Error(`Action "${action.type}" is not a valid action.`)
  }
}

A reducer is a concept where one function can take in many different values, and depending on what that value is, will return a single new piece of data.

A bit more concretely:

Our game reducer will take in an action (which is an object) and we'll use its type value to determine what to do.
New Game: return a new game, as defined by the initial state.
Toggle Player: return whatever values are currently in our game's state, updating the board, and the current player to the new values passed in.
End Game: return whatever values are in state, set gameOver to true, update the message, and update the board.
Update Message: A handy way to keep everything the same except for the message.
If the type value is something we didn't account for, throw an error.

The nice thing about react is that every time we update our component's state, the component will automatically re-render itself and any children components.

As such, the most-current version of our state will always be in the gameState variable. Let's bring this full circle by using the dispatchGameState.

Updating our state

Just like our gameReducer contains all the ways our state can update, our play function will be in charge of doing the actual updating.

We'll start by allowing players to place their tokens, alternating turns. To do so, update your play function with the following code, just after our for-loop:



const nextPlayer =
  gameState.currentPlayer === gameState.player1
    ? gameState.player2
    : gameState.player1

dispatchGameState({ type: 'togglePlayer', nextPlayer, board })

We start using a ternary operator to see who the next player is. Then we update our game by calling dispatchGameState, passing in the updated player, the updated board, and most importantly, the type.

🗒️ Recall that the our gameReducer looks at the type value to determine how our state should update.

Save and run the game. You should now be able to place alternating tokens 🎉

Wrapping up the game

Our game is near complete, though we should probably add in the ability to check for a win, display a message to the players, and restart the game!

Fortunately for us, the most of the work is done, we'll just want to add in the relevant state updates.

The logic to update the game update the game is so similar to what we've already accomplished that I'll just link out to the repo so that you can view what the final screen looks like. To access it, just click here

You'll notice that the logic to update the game has been abstracted away in a checkForWin function.

That function just does a few optimized for-loops and I chose not to copy/paste it here to focus on understanding the concepts.

This function is also in the repo I linked to above, feel free to open up your gameUtils.js file and paste in all the code from this link. Just be sure to import both the checkForWin function and the generateNewBoard function into the Connect4.js file.

The last thing to do is to have the ability to start a new game😎

For this, we'll want to use the generateNewBoard function from our gameUtils file. Update your "New Game" button to look like this:



<Button
 colorScheme="purple"
 className={gameStyles.button}
 onClick={() => {
  dispatchGameState({ type: 'newGame', board: generateNewBoard()})
 }}
>
 New Game
</Button>

Make sure all your files are saved and you should have a working Connect4 game🎉

Conclusion

As you can see, creating a turn-based game in React is actually more about JavaScript concepts and how data flows in a React project.

I hope you had as much fun building this out as I did and if you have any suggested enhancements or updates you'd like to see definitely let me know!

How: Auto-Populated Schema Fields in AWS Amplify

Michael Liendo — Wed, 05 May 2021 19:10:30 +0000

Unsplash photo by Luke Richardson

Not too long ago, I was building a schema using AWS Amplify.

Simplified a bit, it looked like this:

type Game @model {
  id: ID!
  gameName: String!
  player1: String!
  player2: String!
  currentPlayer: String!
  board: AWSJSON!
}

Context

🗒️ For context on this scenario: Amplify is using AppSync under the hood -- A managed GraphQL API.

Furthermore, here's a breakdown of the field values:

Value	Description
ID!	A string that is implied to be unique. Required.
String!	Any sequence of string characters. Required.
AWSJSON!	Any value that is able to be stringified as JSON. This will automatically do the stringifying. Required.

The last piece to talk about is the @model directive.

By just adding that directive to our schema, Amplify will create mappings for common CRUD operations. The mapping will be between AppSync and DynamoDB.

In short, we'll have a way to create, read, update, and delete a game from our frontend, and have that data available in a database.

Learn and Be Curious

When I push this model up to AWS using the Amplify CLI:

amplify push

Amplify will generate files so that I can perform those CRUD operations from my frontend. So to create a game, I would call the necessary methods, passing in the query, and the required fields:

const board = [[], [], []]
API.graphql(
  {
    query: createGame, 
    variables: 
    {
      input: {
        player1: "Michael",
        player2: "Jessica", 
        currentPlayer: "Michael", 
        board: board
      }
    }
)

🗒️ Note that we didn't provide an id -- a required field.

The method above will return a JavaScript Promise. Assuming the call to create a game is successful, we will be able to dive into the response and see the following object returned:

{
  __typename: "Game",
  id: "s0m3-long-s3qnenc3",
  createdAt: 24324322 // an ISO Date
  updatedAt: 24324322,
  player1: "Michael",
  player2: "Jessica", 
  currentPlayer: "Michael",
  board: "[[], [], []]"
}

Where did the extra fields come from?

Well, looking at the AppSync documentation for scalar types, you'll find this snippet:

Recall that there is a mapping between AppSync and DynamoDB. The image above is a request mapping. Written in VTL or Velocity Template Language.

In short, it's a way to specify data that goes from AppSync to DynamoDB. In this case, it's creating a unique value and adding it to the id field.

"So if Amplify is doing this part for us, then where can we find it?"

Great question, glad you asked!

Amplify provides all of the mapping templates in the resolvers directory. Taking a peek inside of the, we see the following:

Here are the main points worth mentioning:

Line 2: If an id value is null, create a value
Line 3: Create a value for createdAt. Apply it to line 5
Line 10: Create the __typename and set it to Game

Conclusion

Understanding the moving parts can be tricky at first, however pulling back the curtains to reveal the magic is greatly beneficial.

Specifically, you've not only learned how certain fields are created automatically but also how you can tweak a VTL template so that your own fields are automatically added as well!

Build Connect4 in React

Michael Liendo — Mon, 03 May 2021 21:10:38 +0000

Connect4 is a great childhood game of mine. So when I saw that the amazing Ania Kubow made it using vanilla JavaScript, I was set on creating my own version using React!

Before getting started, if you'd like to play the game that we'll be building in the first 2 parts of this series, you can do so here.

Understanding Connect4

For those not familiar with the game, here's the basic structure and ruleset:

A game is played on a grid made up of 6 rows and 7 columns
Players take turns adding a token to a column, columns fill from bottom to top
A game is won if a player manages to get 4 of their tokens lined up either vertically, horizontally, or diagonally

Here's a preview of what our finished game will look like:

Stack Overview

To help in quickly building out our project in order to focus on the actual game logic, I'll be using the following tools:

NextJS -- Used to scaffold out our React project with a friendly developer experience.
ChakraUI -- Used to quickly add styling and alignment.
useReducer -- As opposed to useState, useReducer will be used to help manage our game logic.

Project Setup

To get started, we'll create a new react project with NextJS by running the following command in our terminal:

npx create-next-app connect4

Once our project is set up, we'll want to install the dependencies needed for styling. Change into your project directory and install the following dependencies:

npm i @chakra-ui/react @emotion/react@^11 @emotion/styled@^11 framer-motion@^4

Now that our dependencies are installed, we can begin setting up our game. Let's kick things off in _app.js. In this file, we'll set up ChakraUI.

Replace the contents of _app.js with the following:

import { ChakraProvider, extendTheme } from '@chakra-ui/react'

function MyApp({ Component, pageProps }) {
  return (
    <ChakraProvider>
      <Component {...pageProps} />
    </ChakraProvider>
  )
}

export default MyApp

Note that all this does is allow our entire application to use the default theme provided by ChakraUI.

🗒️ Feel free to delete any of the global styles in styles/globals.css as we won't be using them. We'll cover global styling in ChakraUI towards the end.

Setting Up Our Game

Looking at the screenshot above, we'll need a title, a button, the game board itself, and an area to display a message.

ChakraUI will make it easy for us to center and vertically stack these components with consistent spacing using the VStack component.

Go ahead and replace the contents of index.js with the following:

import { Connect4 } from '../components/Connect4'
import { Heading, VStack } from '@chakra-ui/react'

export default function Home() {
  return (
    <VStack spacing="3rem">
      <Heading>Connect 4</Heading>
      <Connect4 />
    </VStack>
  )
}

👀 Notice that in the above code snippet, there is an import for Connect4 that lives outside of the pages directory, inside a directory called components called Connect4.js.

Go ahead and create that file as we'll be working on it next.

Creating The Gameboard

As we code along, I want to make sure we understand the responsibilities of our game. As such, here is what our game will be in charge of:

A game knows how to reset itself
A game knows who's turn it is
A game knows the current positions that have been played
A game knows if a winner has been declared
A game knows what message, if any, needs to be displayed

Using the above as a set of requirements, we can begin modeling what the initial state will look like for our game.

In Connect4.js Add the following:

//1
import { useReducer } from 'react'
import { Row } from './Row'
import { Button, Text } from '@chakra-ui/react'
import * as gameStyles from '../styles/Home.module.css'

//2
const gameReducer = (state,action) => { return state}

//3
const initialGameState = {
  player1: 1,
  player2: 2,
  currentPlayer: 1,
  board: [
    [null, null, null, null, null, null, null],
    [null, null, null, null, null, null, null],
    [null, null, null, null, null, null, null],
    [null, null, null, null, null, null, null],
    [null, null, null, null, null, null, null],
    [null, null, null, null, null, null, null],
  ],
  gameOver: false,
  message: '',
}

export const Connect4 = () => {
  const [gameState, dispatchGameState] = useReducer(
    gameReducer,
    initialGameState
  )

//4
  const play = (c) => {}

  return (
    <>
      <Button
        colorScheme="purple"
        className={gameStyles.button}
      >
        New Game
      </Button>

//5
      <table>
        <tbody>
          {gameState.board.map((row, i) => (
//6
            <Row key={i} row={row} play={play} />
          ))}
        </tbody>
      </table>

      <Text>{gameState.message}</Text>
    </>
  )
}

Whoa, that's a lot of code all at once! Let's go through the commented numbers and understand what is happening.

We're bringing in useReducer to manage our state, a component called Row (feel free to create the file now), and a few self-explanatory components from ChakraUI.
Our state will be managed by a reducer. We'll fill this out in a bit, but in the meantime, it's just going to be a function that takes in the current state and an object called action. Lastly, it will return the state.
Speaking of state, remember when we listed out what a game is in charge of? We can use those bullet points to set up our initial state. In this case, an object. The most important piece is the board property. We use an array of arrays to represent a Connect4 grid of 6 rows and 7 columns. A game with no moves defaults to null. As players place their pieces, we'll substitute null with either a 1 or a 2 (for player 1, or player 2).
All of our game logic is going to be encompassed in a play function. This function, coupled with our useReducer, will be the heart of our application.
To represent our Connect4 board, we'll use a table.
We'll iterate over each array contained in our board array from our state. For each iteration, we'll create a Row component. Again, if you haven't already created this file, go ahead and do so now.

Wrapping Up Our Styling

The last bit is to create each Row, which in turn, consists of a bunch of Cell components.

Aside from adding a Flex component from ChakraUI to add some basic layout, this code is how most presentational components in React are structured. In Row.js add the following:

import { Flex } from '@chakra-ui/layout'
import * as gameStyles from '../styles/Home.module.css'

export const Row = ({ row, play }) => {
  return (
    <tr>
      {row.map((cell, i) => (
        <Cell key={i} value={cell} columnIndex={i} play={play} />
      ))}
    </tr>
  )
}

const Cell = ({ value, columnIndex, play }) => {
  let color = 'whiteCircle'

  if (value === 1) { color = 'redCircle'} 
  else if (value === 2) { color = 'yellowCircle'}

  return (
    <td>
      <Flex
        justify="center"
        align="center"
        className={gameStyles.gameCell}
        onClick={() => {
          play(columnIndex)
        }}
      >
        <div className={gameStyles[color]}></div>
      </Flex>
    </td>
  )
}

To expand on this a bit, we are creating two components. One called Row that will take in an array containing 7 null values. Each index in the array represents the column of the Connect4 board.

In game terms, to place a token on the board, we don't care what row we're in, we only care what column we're in. Using that logic, we create a Cell component that renders out the circles for the board:

By default, an untaken area on the board will be a white circle
Player 1 will be represented by a red circle
Player 2 will be represented by a yellow circle.

Every time a Cell is clicked, we'll call the play function (that we stubbed out in Connect4.js) and passing in the index of the column.

Adding Styling

I'm sure you've noticed by now that we've been passing around this line of code:

import * as gameStyles from '../styles/Home.module.css'

That file was created for us, but it doesn't contain any of the styles that pertain to our app. Let's update that file to only contain the following:

.gameCell {
  height: 70px;
  width: 70px;
  background-color: #1990ff;
  cursor: pointer;
}

.whiteCircle,
.redCircle,
.yellowCircle {
  height: 60px;
  width: 60px;
  border-radius: 100px;
}

.whiteCircle {
  background-color: #fff;
}

.redCircle {
  background-color: rgb(251, 42, 42);
  transition: background-color 0.5s;
}

.yellowCircle {
  background-color: rgb(243, 239, 20);
  transition: background-color 0.5s;
}

The above has some basic styling that makes our board blue, sets the colors for our circles, and because I was feeling fancy, adds a half-second transition for the circles to change from white to either red or yellow.

As promised, the last thing we'll do in this post is to add some global styling using ChakraUI

In _app.js, we'll extend the default theme with the following object:

// _app.js
import { ChakraProvider, extendTheme } from '@chakra-ui/react'

const theme = extendTheme({
  styles: {
    global: {
      body: {
        backgroundColor: '#8fc2e5',
      },
    },
  },
})

In my screenshot of the game, you'll notice that I also have a background image. To add this, I added a backgroundImage property to the theme, and generated a background image from hero patterns.

To view you game, start the server:

npm run dev

🎊 Congratulations! If all went well, you now have a static gameboard that looks like this:

To view the player circles in your game, feel free to change the parts of your state and they should reflect in your game:

That's it for this section. In the next part, we'll tie things together by adding all of the code needed to have a functioning turn-based game.

Thanks so much for checking out this tutorial and I look forward to catching you next time!

Intro to API Gateway

Michael Liendo — Mon, 03 May 2021 19:49:16 +0000

We’re halfway through and we have already discussed so much! Today, we’re going to start tying our knowledge together so that we can create practical applications.

Kicking things off, we’re going to talk about API Gateway.

API Gateway + Need to Know Terms

This service allows us to quickly create endpoints for us to retrieve data.

Much like the post on S3, API Gateway is a service that can help quite a bit once you get up and running. However, in practical terms, we’ll be focusing on how we can quickly use it in our frontend applications.

API Gateway comes in 3 flavors: REST, WebSocket, and the more newly announced HTTP. As usual, now is a pretty good time to knock out some definitions.

Method: The action that should be applied when interacting with your data endpoint ie) PUT, POST, GET, DELETE

Resource: A user-named item regarding your data. Ie, if you are creating an API about pets, then /pets is a likely resource. Each resource has one or more methods attached to it.

REST Endpoint: A URL that will perform This allows full customization over how we would like to create our APIs.

WebSocket Endpoint: Creates an open connection to allow for near-real-time communication.

🔥Protip: AWS has better options if you’re considering WebSockets with API Gateway.

HTTP Endpoint: Slightly less flexible than REST Endpoints, while offering 40% of the cost savings and much of main functionality.

Stage: An environment where your API lives. Typically used to keep separate production and development environments.

🏗️ Creating our API

🗒️ This section assumes that you have completed the previous day’s task of creating a pet Lambda. If not, refer back to that email before continuing. However, if you just need a quick refresher, we created and deployed the following lambda function:

Log into your account and search for API Gateway from the top search bar.

Next, follow the steps below:

Under HTTP API, select “Build”
Select “Add Integration”, then select Lambda
Select the region you used to create your Lambda function
Click in the “Lambda Function” box and select your lambda
In the “API name” field, name your API pets-api
When you're done, select “Next”

Almost done!

On the next page, we’ll be configuring our API endpoint. Go ahead and follow these steps:

For the Method field, change it to GET
For the Resource Path, change that to /pets
Click Next

We’re not going to configure another stage, so go ahead and click next.

If all went well, your screen should look just like mine in the screenshot below

🎉 Congratulations! You just created an API endpoint on AWS without writing any code!

Testing your endpoint

With your API selected, you should see an “Invoke URL”. If you were hasty and clicked it, you already know it doesn’t work 😅

That’s because we didn’t assign anything to the root or / resource. Our resource is /pets.

Copy the Invoke URL paste it in your browser’s search bar, ensuring that you appends /pets to it. You should now see your list of pets!

If you’re just wanting to use this endpoint on your server, then you’re all done! However, chances are you want to use this in your frontend applications too. Unfortunately, if you try that now, you’ll be greeted by a friend that we’ve all met:

CORS

It’s saying “hey, server to server is fine, but server to the browser isn’t configured”.

Let’s fix that.

Back in the AWS Console:

Select the CORS tab on the left-hand side (under Develop)
Select the Configure button Under Access-Control-Allow-Origin enter an asterisk
Click Add, then Save

🗒️ Access-Control-Allow-Origin with an asterisk as the value allows anyone to call our endpoint. In many scenarios, you’ll want to lock that down to just your website’s domain.

🎉 Congratulations! You just enabled CORS for your publicly available API endpoint. Feel free to test it out in a Codesandbox!

Pricing

API Gateway doesn’t charge for the first one million API calls. In my region (and most others) pricing after the free amount is $1.00 for every million requests.

Not bad at all!

https://aws.amazon.com/api-gateway/pricing/

Over the course of a few posts, we have already covered a lot! Next time, we’ll learn how to persist data to a NoSQL database by taking a look at DynamoDB.

See ya then!

Intro to AWS Lambda

Michael Liendo — Wed, 28 Apr 2021 07:50:35 +0000

Cover image by Thomas Couillard

Hello Again 👋🏽

Let’s get the meme out of the way: Serverless services still have a server. The naming is just used to imply that it’s a server that you no longer have to manage.

This means even though there is a server involved at some point, we don’t have to mess with it. So instead of patching OS updates, setting up scaling rules, etc. we can focus on our business logic and deploy a function.

That’s right. A lambda is just a function that lives on AWS. You put your code in it, and some kind of event calls the function.

🗒️ Need to know terms

Serverless: A managed service that automatically scales based on your traffic where billing is based on usage.

Lambda: A type of serverless service that allows us to write code that executes in a function that is called by some type of event.

Trigger: An event that invokes a lambda

It’s worth reiterating, that a Lambda is event-driven. That event can be anything from someone coming to your website, to a new user signing up, to some scheduled interval that runs every 5 minutes or so. There’s a lot of flexibility when it comes to what triggers the event.

🏗️ Creating our first Lambda

Using a step-by-step process, let’s go ahead and create our lambda function:

Log into your AWS account, search for Lambda using the search bar at the top, and select the first option
Click the “Create function” button
Starting from scratch, name your function pets-get-func
Click the “Create function” button

🎉 That’s it! Congratulations on creating your Lambda function!

🟡 Reviewing the Lambda Dashboard

With our function created, let’s take a moment to explore what we’re now presented with.

In the above screenshot, the top portion is known as the “Function Overview”. Since Lambda’s are event-driven, we can configure a trigger as well as the destination for the response.

Further down, we see the “Code Source” panel. While it’s fine to write code in this built-in editor (as we’ll soon do), for bundles of code larger than 50mb, we can also use the “Upload from” dropdown.

In a typical flow however, you’ll most likely use the CLI or another tool to push your function code to AWS.

💫 Running our lambda function

As you can see from the code editor, a lambda function can really be as simple as something that just returns some data. A couple of things to note:

Functions are stateless. So you’re not going to want to put any variables outside your function handler.
The event argument contains information relating to whatever triggered the function. Since many things can do just that, this argument is contextual.

Go ahead and update your function so that it looks like the screenshot below and click “Deploy”

Next up is to create a test event for our event variable:

Click Test
Name your event “exampleEvent”
click Create at the bottom. Now that we created a test event, we can click the Test button one more time and our function will run.

🎉 Congratulations on running your lambda function!

While viewing the execution results, we can see the response body as well as meta information such as how long the function took to run. Execution time is something to be mindful of because it relates to how you’ll be billed.

Speaking of billing, let’s wrap this up with a chat on pricing.

💸 Pricing

A trend with serverless services is that you’ll typically pay for two things:

compute: How long it takes for something to run

requests: How many times your service is used

Using today's default lambda in us-east-2, the pricing is as follows:

Compute: $0.0000000021 per/ms

Requests: $0.20 per 1M requests

👀 If those penny-fractions get you worried, fear not, AWS also provides a free amount of usage each month:

1M free requests per month and 400,000 GB-seconds of compute time per month

https://aws.amazon.com/lambda/pricing/

As we get along further in understanding some of the core AWS services, I do want to make sure your account is set up correctly to avoid any unexpected charges 😅

So for those interested, I created a video you can checkout to make sure you're covered