However, adding a third-party SaaS when the rest of your application backend is built on AWS can seem tricky. That's why in this post, I'm going to show exactly how to put the two together.

Application Overview

🗒️ All the code relating to this post can be found in the repo above.

Typically, when I add authorization with AWS, it's with Amazon Cognito. In Amplify Gen 2, this is done for you since when you scaffold your application with npm create amplify, both a data and auth resource are created. However, the underlying API (AWS AppSync) has a trick up its sleeve: You can create a Lambda function to have complete control over how the authentication works. This Lambda function can then be set as the authentication mechanism on the API instead of a Cognito userpool.

export const data = defineData({
    name: 'fullstack-with-clerk',
    schema,
    authorizationModes: {
        defaultAuthorizationMode: 'lambda', // set the mode
        lambdaAuthorizationMode: {
            function: APIAuthorizer, // apply the lambda function
        },
    },
})

Understanding AWS AppSync Lambda Authorizers

Lambda authorizers in AWS AppSync work differently than those found in other API services on AWS. In my opinion, they're much simpler.

In short, as long as you return an object with an isAuthorized boolean, you're all set. How you form the true or false value for that boolean is up to you.

Any authorization tokens passed to our API will appear on the event.authorizationToken parameter. In our application, we'll use the JWT of the user from Clerk, verify it, and then decode it to get the users sub. If all of that works, then we know they are authorized:

import { Handler } from 'aws-lambda'
import jwt, { JwtPayload } from 'jsonwebtoken'
import * as crypto from 'crypto'
import { env } from '$amplify/env/clerk-api-authorizer'

const jwkToPem = (jwk: string) => {
    const keyObject = crypto.createPublicKey({
        key: jwk,
        format: 'jwk',
    })

    const pem = keyObject.export({
        type: 'spki',
        format: 'pem',
    })

    return pem
}
//make sure lambda runtime supports `fetch` (v >= 20)
export const handler: Handler = async (event: {
    authorizationToken: string
}) => {
    const token = event.authorizationToken
    const secret = env.CLERK_API_KEY
    const validDomains = ['http://localhost:5173']

    const res = await fetch('https://api.clerk.com/v1/jwks', {
        headers: {
            Authorization: `Bearer ${secret}`,
        },
    })

    const data = await res.json()
    const pem = jwkToPem(data.keys[0])

    let decoded: JwtPayload | null = null
    try {
        decoded = jwt.verify(token, pem) as JwtPayload
    } catch (e) {
        console.log('the error', e)
        return 'Invalid token'
    }

    if (!decoded || !validDomains.includes(decoded.azp))
        return { isAuthorized: false }

    return {
        isAuthorized: decoded.sub ? true : false,
        resolverContext: { owner: decoded.sub },
    }
}

A couple of notes on the code above:

1. The env object from Amplify is Gen 2 specific. More details can be found here. If not using Gen 2 (AWS CDK), you'll have to get the Clerk secret from SSM or another mechanism.

2. The endpoint 'https://api.clerk.com/v1/jwks' was figured out by following the Clerk docs for manually verifying the JWT. The rest is just getting the returned keys, generating a pem file, and verifying the token with the pem.

3. In the return statement, I'm passing resolverContext. Think of this as metadata that by API resolvers can then make use of. It will be available as context.identity.resolverContext.owner. If you just want authenticated users to access your API, then this is not needed, but this is important is you want to scope data to a particular user.

The repo is a fullstack example with react-router-dom. If you want to learn how to create a fullstack app with Clerk and react-router-dom, checkout the getting started page from Clerk.

API Endpoints with Clerk and AWS AppSync

If your goal is to have Clerk provide the authentication for an app where everyone signs in and shares data, then the rest is pretty straightforward:

In your Amplify Gen 2 schema, you can have Amplify create your resources as normal:

const schema = a.schema({
    Milestone: a
        .model({
            title: a.string().required(),
            description: a.string(),
        })
        .authorization((allow) => [allow.publicApiKey(), allow.custom('function')])
})

That will create the resolvers for you to be able to to create, read, update, and delete.

However, typically, you'll want to scope those operations so that only the logged in user can manipulate the data, without affecting everyone else. This is called owner-based authorization, and what I'll show.

🗒️ The following JS resolvers work both with Amplify Gen 2 and the AWS CDK

Creating an item with owner

Imagine we already have a datasource: a DynamoDB table setup. Also, recall that our Lambda function used for authorization is passing the owner on the resolverContext.

import { util } from '@aws-appsync/utils'
import * as ddb from '@aws-appsync/utils/dynamodb'

// This is the request to our database
export function request(ctx) {
    const { owner } = ctx.identity.resolverContext
    const id = util.autoId()
    const now = util.time.nowISO8601()
    const item = {
        ...ctx.args,
        id,
        owner,
        createdAt: now,
        updatedAt: now,
    }
    const key = { id }
    return ddb.put({ key, item })
}

// This is the response from our database
export function response(ctx) {
    return ctx.result
}

Because AWS AppSync has first-class support for DynamoDB, we can make use of the AppSync util package, as well as the DynamoDB helpers package.

We combine those two to create things like a random id, set the time using now.ISO8601, and put the item in the table with its owner field.

The result is simply the item as it was stored in DynamoDB.

In short, any signed in user can create.

Getting an item by owner

When it comes to getting an item from DynamoDB, we effectively say, "Any signed in use can get an item from the database, but for the database to respond back to the client with the information, the owner field on the item has to match the owner field from the Lambda authorizer:

import { util } from '@aws-appsync/utils'
import * as ddb from '@aws-appsync/utils/dynamodb'

export function request(ctx) {
    // get a todo by its id (API protects this so only auth users can call it)
    return ddb.get({ key: { id: ctx.args.id } })
}

export function response(ctx) {
    //if the owner field isn't the same as the identity, the throw
    const { owner: clerkUser } = ctx.identity.resolverContext
    const { owner: ddbOwner } = ctx.result
    if (ddbOwner !== clerkUser) {
        util.unauthorized()
    }

    return ctx.result
}

So long as that is the case, then return the data.

Updating an item if owner

Updating is fun because now we get to use DynamoDB conditions to do a lot of the work for us:

import { util } from '@aws-appsync/utils'
import * as ddb from '@aws-appsync/utils/dynamodb'

export function request(ctx) {
    const { id, title, description } = ctx.args
    const { owner } = ctx.identity.resolverContext
    const now = util.time.nowISO8601()

    const updateObj = {
        title: ddb.operations.replace(title),
        description: ddb.operations.replace(description),
        updatedAt: ddb.operations.replace(now),
    }

    // update it if owner.
    return ddb.update({
        key: { id },
        update: updateObj,
        condition: { owner: { eq: owner } },
    })
}

export function response(ctx) {
    return ctx.result
}

Think of a form in a web app, were it populates all of the data about the item in various input boxes. The user can then update them and click submit. The backend get all of the information and simply updates the item in the database. What I love about updating is it shows the replace utility as well as the time.nowISO8601 utility for updating the timestamp.

Deleting an item if owner

Deleting is similar to getting an item, except we get to rely on DynamoDB conditions to make sure it's only deleted is the owner fields match:

import * as ddb from '@aws-appsync/utils/dynamodb'

export function request(ctx) {
    // delete a todo by its id if it's the owner
    const { owner } = ctx.identity.resolverContext
    return ddb.remove({
        key: { id: ctx.args.id },
        condition: { owner: { eq: owner } },
    })
}

export function response(ctx) {
    return ctx.result
}

Pagination (listing items if owner)

I saved this one for last because it's its own way of doing things. In a naïve implementation, we may be tempted to just return an array of items. In fact, if we were scanning the table, that's what we'd get back. But in a real-world scenario, we want to efficiently query the data in our table and return a placeholder (token) if there are more items than our limit is set for:

import * as ddb from '@aws-appsync/utils/dynamodb'

export function request(ctx) {
    const { owner } = ctx.identity.resolverContext
    return ddb.query({
        query: { owner: { eq: owner } },
        index: 'milestonesByOwner',
        limit: ctx.args.limit || 25,
        nextToken: ctx.args.nextToken,
    })
}

export function response(ctx) {
    const { items = [], nextToken } = ctx.result

    return { items, nextToken }
}

There's nothing inherently hard about this example, but it takes consideration. limit and nextToken aside, the index is what matters most here.

By default, our database is set with a primaryKey of id. However, for listing content, we want only search through items by their owner field. In short, we want a globalSecondaryIndex.

If not using Amplify and just using vanilla CDK, this can be achieved fairly easily as shown in my CDK starter repo. And if using Amplify Gen 2, this can be achieved as shown in the amplify/data/resource.ts file.

Conclusion

That's all there is :) The repo has all of the methods used on the frontend so that you can practice making calls to the backend. If you enjoyed this tutorial and would like to see AWS integrated with other resources, let me know by dropping a comment!

Until next time, Happy Coding 🦦

In this post, I'll walk through how to quickly get an application setup with Tally forms and extend it into the AWS ecosystem via webhooks. This will allow us to build out an app that can email a digital product to our users after it's fetched from an S3 bucket.

Application Overview

The frontend is fairly simple. Essentially, give a form created by Tally, a user can fill it out and through the use of Tally webhooks, our Lambda function can be triggered.

The backend is architected using Amplify Gen 2 and simply creates a Lambda function, and an S3 bucket.

The repository for this project contains all of the code needed to get this working:

The core logic for this application is primarily to get the item from S3 as a presigned URL, and then to send an <a> tag with the href value set to the presigned URL:

    // Get the song url from S3

    const url = await generatePresignedURL(
        env.SONG_STORAGE_BUCKET_NAME,
        env.SONG_PATH,
        3600 //expires in 1 hour
    )
    // Send email with the song
    await sendHTMLEmail(
        env.VERIFIED_SES_FROM_EMAIL,
        [email],
        'Your song has arrived!',
        `
        <html>
        <body>
        <h1>Hello from Focus Otter Music!</h1>
        <p>Hey ${firstName}, thanks so much for your purchase!</p>
        <p>Here is <a href="${url}">your song</a>. Hope you enjoy!</p>
        </body>
        </html>
    `
    )

Conclusion

This is a great starter project for those wanting to get into AWS. However, there are times where the file you'd like to send may be too large to embed in the body of the file. For those cases, you'll want to send it as an attachment. Fortunately, I have a blog post setup that walks through exactly how to do that as well!

For those reasons, in this post, I'll show how to use Stripe and AWS to create an application that allows users to buy a product and have it emailed to them!

Application Overview

All of the code for this project can be found here:

The entry point of this application is based on a Stripe payment link that is triggered when a user clicks the "Get Your Song🎵" button.

Once a user makes a purchase, a Lambda function listens to the checkout.session.completed event type to perform code. To make sure only Stripe is authorized to process these events, the Stripe webhook signature is validated.

After validation, we can grab our song from Amazon S3 and email it to the customer as a file attachment. As opposed to an inline email, file attachments allow for larger file upload.

🗒️ This setup assumes a verified email address. If you're SES account is in the sandbox, ensure a verified email is being used during development. The YouTube video has tips on getting out of the sandbox and moving to production.

The entire application flow looks like this:

Backend Setup

Using AWS Amplify Gen 2, I'm able to not only create my AWS services, but also have a full TypeScript experience. This means less errors and a simpler developer experience.

Creating the Amplify backend

In previous versions of Amplify, a backend was scaffolded and iterated on using the Amplify CLI. In Gen 2, the CLI is only used as an entry point while the iteration happens via TypeScript:

npm create amplify@latest

This will create both a data resource (API + database) and an auth resource (defaults to email sign in).

In this application, we're using neither, so as you can see in the repo, I deleted those respective folders.

Creating an S3 bucket

The S3 bucket needed to contain our MP3 needs to authorize our to-be-created Lambda function with read access. Fortunately, doing so is around 5 lines of code.

Using the GitHub repo as reference, I have following piece of code in the amplify/storage/resource.ts file:

import { defineStorage } from '@aws-amplify/backend'
import { stripeCheckoutSongFunc } from '../functions/stripe-checkout/resource'

export const storage = defineStorage({
    name: 'amplifyStripeSongCheckout',
    access: (allow) => ({
        'products/*': [allow.resource(stripeCheckoutSongFunc).to(['read'])],
    }),
})

Creating the Lambda function

The Lambda function needing to serve as the webhook for Stripe is similarly simple to setup. In the amplify/functions/stripe-checkout file I give it an name, an entry point for my business logic, and pass in a few environment variables:

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

export const stripeCheckoutSongFunc = defineFunction({
    name: 'stripe-checkout-song',
    entry: './main.ts',
    environment: {
        // STRIPE_SECRET: secret('stripe-secret'),
        // STRIPE_WEBHOOK_SECRET: secret('stripe-webhook'),
        SONG_KEY: 'products/amplify-song.mp3',
        FROM_EMAIL_ADDRESS: 'mtliendo@focusotter.com',
    },
})

Initial sandbox deploy

With our services scaffolded, now is a good time to perform an early deploy of our backend. Deploying early is a great way to catch problems in syntax before they cascade into bigger problems. Before doing so, we have to add these two services to our backend stack.

import { stripeCheckoutSongFunc } from './functions/stripe-checkout/resource'
import { defineBackend } from '@aws-amplify/backend'
import { storage } from './storage/resource'
import { FunctionUrlAuthType } from 'aws-cdk-lib/aws-lambda'
import { PolicyStatement } from 'aws-cdk-lib/aws-iam'

const backend = defineBackend({
    storage,
    stripeCheckoutSongFunc,
})

In addition to adding the storage and stripeCheckoutSongFunc services that we created, we'll want to both generate a function URL that we can pass to Stripe, and provide permission for our function to use the SES service. To accomplish that, I added the following just below what's currently in that file. Once done, I can deploy my app to AWS:

const stripeWebhookUrlObj =
    backend.stripeCheckoutSongFunc.resources.lambda.addFunctionUrl({
        authType: FunctionUrlAuthType.NONE,
    })

backend.addOutput({
    custom: {
        stripeCheckoutSongFunc: stripeWebhookUrlObj.url,
    },
})

backend.stripeCheckoutSongFunc.resources.lambda.addToRolePolicy(
    new PolicyStatement({
        actions: ['ses:SendEmail', 'ses:SendRawEmail'],
        resources: ['*'],
    })
)

npx ampx sandbox

This long-running service will continuously watch for backend changes and automatically redeploy our application when those occur.

This is great so far, but the application doesn't make use of any secrets from Stripe. Let's fix that.

Accessing secret values from Stripe

This application needs 2 secret values: A stripe webhook secret, and the Stripe account secret. The secret key is pretty simple to gather, just make sure you don't share it!

The webhook secret can only be given once a webhook has been entered, fortunately, by clicking on the "Webhooks" tab in Stripe, we can do just that:

Once complete, you'll want to grab the "signing secret" and make sure you never commit or share it!

All that's left is to create your product and get a URL for the payment link. This can be done by clicking the + icon in the top-right, or simply pressing c, l on any page in Stripe(🤯).

I setup mine like this, but feel free to setup yours however you like!

The payment link is what is put on the button on our landing page.

Storing Secret Values

It's worth noting that the secret function provided by Amplify (as seen in our Lambda function resource) will take in a secret name and automatically handle grabbing the secret value. However, setting the secret in the first place is handled via the CLI:

npx ampx sandbox secret set stripe-secret

# enter the secret value:

I ran that command for both the stripe-secret and the stripe-webhook values. Afterwards, make sure to uncomment the environment variables in the resource file.

Handling Backend Logic

With our resources created, and secrets added, it's time to setup the business logic for our Lambda function.

While the main.ts file is essentially the "glue" that puts the logic together, the logic is really divided into 3 sections:

1. Verifying the Stripe signature

2. Getting the song from S3

3. Sending the email as an attachment

Verifying a Stripe signature

As shown in amplify/functions/stripe-checkout/helpers/verifyStripeWebhook.ts, this function is generic and ready to be reused across applications:

import Stripe from 'stripe'
import { env } from '$amplify/env/stripe-checkout-song'

type Event = {
    headers: {
        'stripe-signature': string
    }
    body: string
}
export const verifyWebhookSig = async (event: Event) => {
    const stripe = new Stripe(env.STRIPE_SECRET)
    const sig = event.headers['stripe-signature']
    try {
        const stripeEvent = stripe.webhooks.constructEvent(
            event.body,
            sig,
            env.STRIPE_WEBHOOK_SECRET
        )
        return stripeEvent
    } catch (err) {
        console.log('uh oh', err)
        throw Error('Invalid signature')
    }
}

It simply expects the Lambda event object and from there pulls off the headers while using the Stripe secret we created to perform the validation.

Getting an Object from S3

This is another file that I templated so that it can be easily reused across projects:

import { GetObjectCommand, GetObjectCommandOutput } from '@aws-sdk/client-s3'
import { S3Client } from '@aws-sdk/client-s3'
const s3Client = new S3Client()

export async function getObjectFromS3({
    bucketName,
    objKey,
}: {
    bucketName: string
    objKey: string
}) {
    let res: GetObjectCommandOutput | undefined
    try {
        res = await s3Client.send(
            new GetObjectCommand({ Bucket: bucketName, Key: objKey })
        )
    } catch (e) {
        console.log('error getting object', e)
    }

    return res
}

Essentially, you pass it the name of the S3 bucket, and the key of the object. Both of these items are stored as environment variables, making this a simple solution for grabbing any item from S3!

Sending the Email as an attachment with SES

Lastly, and still in a reusable fashion, this we want the ability to send an email with both text, and an attachment. As opposed to sending an html formatted email, this involves dropping down to a raw email format:

import { SESv2Client, SendEmailCommand } from '@aws-sdk/client-sesv2'
import { env } from '$amplify/env/stripe-checkout-song'
const sesClient = new SESv2Client()

export const sendSESEmailWithAttachment = async (
    fileBuffer: Buffer,
    toEmailAddresses: string[],
    fileContentType: string,
    fileName: string
) => {
    const myEmail = env.FROM_EMAIL_ADDRESS
    const rawMessage = `From: ${myEmail}
To: ${toEmailAddresses.join(', ')}
Subject: Email with MP3 Attachment
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="boundary_string"

--boundary_string
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit

This email has an MP3 attachment.

--boundary_string
Content-Type: ${fileContentType}
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="${fileName}"

${fileBuffer.toString('base64')}
--boundary_string--`

    const sendEmailParams = {
        Content: {
            Raw: {
                Data: Buffer.from(rawMessage),
            },
        },
    }

    const sendEmailCommand = new SendEmailCommand(sendEmailParams)

    try {
        const result = await sesClient.send(sendEmailCommand)
        console.log(`Email sent successfully. Message ID: ${result.MessageId}`)
    } catch (err) {
        console.error('Error sending email:', err)
    }
}

🗒️ It's ugly. But I think it's just the long string that makes it look bad.

Conclusion

With those 3 pieces in place, the amplify/functions/stripe-checkout/main.ts file simply makes use of them to create our application flow.

If wanting to clean up and delete the resources, running npx ampx sandbox delete will do just that (or cancelling out of the running sandbox will trigger a prompt). Also worth noting is that any secrets we added in the sandbox must be manually removed with npx ampx sandbox secret remove [secret-name].

What I love about this project is that it can be reused anytime you want to sell any digital item online! Making it a super fast an easy solution!

Hope this helped and if you enjoyed this piece let me know by dropping a comment!

Until next time, Happy Coding 🦦

Yet, there's something to love about the flexibility of putting in just one earbud, or exercising without getting tangled in wire, or even the different customizations I can make with pressing, long-pressing, sliding etc.

Maximum ease-of-use vs maximum flexibility.

In case it's not apparent, that's how I felt when comparing AWS Amplify Gen 2 vs my custom AWS solution with the AWS CDK when it came to building fullstack apps.

In this post, I'll discuss some of the similarities between these solutions, their differences, and when I would use one over the other.

🗒️ While this post is intended for fullstack developers, It slants towards those with knowledge of the AWS CDK. If coming from the other end and are more of a frontend developer, I encourage you to read my last post.

AWS CDK for Power and Flexibility

When your next great idea strikes for a fullstack application, there are plenty of times you'll want to reach for the AWS CDK directly. This wrapper around AWS Cloudformation gives developers the freedom to write their backend in TypeScript, Python, Java, and other languages. This can be a huge benefit and unblocker in itself for developers and teams.

Surface Level

Creating a new fullstack application, where the backend is powered by the AWS CDK is powerful and simple:

npm create vite@latest ./ && \
md _backend && \
cd $_ && \
npx aws-cdk init -l typescript \

If you need authentication, an API, a database, file storage, etc, you get to craft those exactly how you want.

Setting up a team-based workflow is also great because you get to specify exactly how you want your workflow to be and what the day-to-day experience will be like.

And when it comes to deployment, you get to have full control on how you'd like it deployed.

These are all great! Personally, from a learning perspective, it also meant I got to understand services at a much more clarified level than using a tool that generated it for me. It helps that I'm never really extending the CDK since I'm working at more or less the same level the whole time. I'm simply building.

Diving Deeper

However, if you re-read the section above and replace each instance of "you get to" with "you have to". Then things start to become much more daunting.

🗒️ It's worth noting that there is a tool called Projen that aims to simplify some of the opinions needed to be made. You can learn more about the Pros and Cons of that package here.

For this reason, I created my own CDK starter repo. It comes with many of the configuration options that I like and simplifies some of the mundane work needed to get my fullstack idea off the ground.

This worked out well because I often build fullstack, monorepo applications. It also comes with basic CRUD operations for my API so I can simply reference them and tweak them accordingly.

At the expense of sounding blasphemous, this was my attempt at creating Amplify Gen 2 before it existed 😅

This is just a personal project though and not something that I guarantee will work for you (I even say so in the readme!).

With that said, while the repo I created uses a CDK construct to deploy a frontend to AWS Amplify, maybe that's not what you want. Perhaps you want to keep your frontend and backend separated in different GitHub repos. That's to say, everytime a backend change occurs, a GitHub action will try to build and deploy your changes to AWS.

That's what I built with my GitHub OIDC repo:

Conclusion

I say all of this to highlight the flexibility, and power in setting this up exactly how you want. However, it's time consuming. If you're in a large organization, you've likely already invested the time into this and have something similar to what I created above.

Though, if you are not a large organization the above is a lot of work and probably enough to say "nevermind". At the end of the day, choosing to understand the tools you use will serve you in the long run--greatly impacting the overall Total Cost of Ownership.

AWS Amplify for Speed and Ease of Use

As the AWS CDK wraps Cloudformation so that customers don't have to write extraneous amounts of YAML, AWS Amplify wraps the CDK to provide structure for building fullstack apps*.

I mentioned in a recent post, AWS Amplify in 2024 is not the Amplify you grew up with. Gone are the days of writing a GraphQL schema, or using predefined storage paths like private , protected , and public.

// Setting up a data model in Gen 2 using TypeScript

const schema = a.schema({
    Todo: a
        .model({
            content: a.string(),
        })
        .authorization((allow) => [allow.guest()]),
})

// Setting up an S3 Bucket with authorization access in Gen 2

const storage = defineStorage({
  name: 'myProjectFiles',
  access: (allow) => ({
    'media/*': [
      allow.guest.to(['read']) 
    ]
  })
})

In fact, in that last post, I showed how to extend the Amplify service so that custom API operations can be made instead of using the .model helper provided by Amplify.

Surface Level

Creating an application using Amplify is similarly simple to the CDK:

npm create vite@latest\
npm create amplify@latest\

The above is all that is needed to create a fullstack application that is powered by AWS and fully developed in TypeScript.

However, I'd be amiss if I didn't point out that TypeScript being used here isn't a personal preference, it's a requirement as opposed to the AWS CDK. This underscores Amplify being targeted towards fullstack teams and developers (more on this in a bit).

If you are a solo developer, you might have one AWS account. If you're serious dev or a small team, you might have SSO setup. If you're a large org, you probably give every developer their own AWS account. These are just a few ways that day-to-day development is done.

In Amplify Gen 2, none of that matters because every project is developed in its own sandbox:

npx ampx sandbox [--profile=focus-otter]

Gone are the days of stepping on each others workflow. Instead, running the command above will not only do a synth and deploy of your application, but it will also generate the appropriate CDKOutputs and put the backend in watch mode.

When it comes to customizations from the basic CRUD operations that Amplify provides, in Amplify Gen 2 extensibility works differently. Gen 2 resources are file-based instead of CLI-based, so adding custom resources means just writing CDK code.

In the code above, notice how I'm using CDK L2 constructs in my application. Also, take notice of how the type of my myCustomCDKStack item is of type Stack.

Not some Amplify wrapped service. Just a plain 'ol CDK stack!

Diving Deeper

The .model part of the data resource will create an AppSync API, a DynamoDB database, associate the necessary roles/permissions, and generate all of the CRUDL operations + subscriptions, and their types.

That's a lot! But is it too much? I personally don't think so. Doing so by hand is boring and mundane. Every application needs those capabilities, yes. Though if you aren't a fan of those particular services...don't use them 🤷‍♂️

What I mean is Amplify doesn't bind developers to those services, but does take the opinion that most developers will benefit from this experience. To prove that, compare my CDK starter repo above, with my Amplify Gen2 starter repo here:

My personal Gen 2 starter (not affiliated with the official Amplify Gen 2 starter) just works, comes integrated with it's own sandbox environment instead of me trying to create my own, and if at any point I want to add more features, I simply drop down to using the CDK.

Amplify is doing for the CDK community what Expo did for React Native.

"But Focus Otter, I don't want to have my backend and frontend bundled together."

Great! Amplify Gen 2 no longer has to be tied to one--in fact, it only cares that your backend is written in TypeScript. What you use it for is completely up to you. This unlocks a new category of use cases that is not only documented, but officially supported by the Amplify team.

More on this feature in a future post!

In Amplify Gen 1, I recall having to do things "the Amplify way". There is still some of that, but as someone who has grown fond of developing with the CDK, doing things the Amplify way feels less like a shove in a direction, and more like a guided hand.

Which to use

It would be too easy to write "it depends" and call it a day. So let me offer some practical advice for building fullstack applications on AWS:

Start with Amplify.

My headphone analogy in the beginning falls apart when I consider how deeply integrated Amplify Gen 2 is with the AWS CDK.

Sure, if you don't know JavaScript/TypeScript, then it's not a good fit. Full stop.

If you're Lambda functions aren't in TypeScript, stay tuned.

Remember, that Amplify Hosting integrates with Amplify Gen 2, but they are separate. So if you have your own set of hosting requirements, you can still build with Gen 2.

I can't stress how critical I've been of this new workflow since testing it out internally--and even now. But it's good, really good. Yes, you can spend time coming up with the solutions using the CDK like how I did, but your time is better spent.

Keep in mind, this post is for the masses. That's to say it's not a silver bullet but rather my current opinion on what should be your goto.

That's enough though leadership for me, for the next few weeks I'll be showing a bunch of fun applications that can be built with Amplify Gen 2!

Until then, happy coding 🦦

Through the lens of Mobile Hub, I learned the foundations of AWS and serverless. However, the tool was buggy, soon deprecated, and shortly after, AWS Amplify came to be.

Through this tool, I didn't have to setup Cloudfront or S3. As a frontend/fullstack developer, I wanted to use something like what Zeit (now Vercel), or Netlify had to offer. AWS Amplify Hosting allowed that.

In addition, the Amplify CLI meant I didn't have to know AWS. I could just use the CLI. From easy use cases where I wanted an S3 bucket:

amplify add storage

To more complex integrations likes creating a GraphQL API with a database and authentication rules:

amplify add api

type Todo @model @auth(rules: [{allow: private}]) {
    id: ID!
    name: String!
}

I felt empowered to build anything.

Through the AWS Community Builders program, I was able to get direct feedback to and from the AWS Amplify team until the Spring of 2021 when I was hired as a developer advocate on the AWS Amplify team.

Learning How to DA and Icarus

As a developer advocate for the Amplify team I loved challenging myself to see how I could build out seemingly-complex applications using the Amplify CLI. I wasn't interested in todo-style or simple CRUD-type applications.

I instead wanted to build social media sites like Instagram, apps that have to pass data to one another like Starbucks, and multi-tenant SaaS applications like Slack.

I would often hit a roadblock, talk to the engineering team, find a workaround, and keep going forward. It wasn't that what I was doing couldn't be done, but there were times when the solution was so far-fetched that I couldn't believe that was the best form of DX we could have.

Naturally, I gave feedback and as expected, the Amplify team delivered. In 2022, the team announced extensibility with AWS Amplify. This feature allowed customers to leverage the AWS CDK to provision services that the Amplify CLI didn't support.

🗒️ This was absolutely the right move. AWS has over 200 services. It'd be ridiculous to have a CLI tool that had all of those services baked in!

Through extensibility, I felt I had better control. The ceiling to what I could build as a sole developer was certainly raised and to this day, I'd say the majority of solo devs could use this and be profitable in both revenue and usage.

The problem was that I -- a solo developer -- had to know:

• A frontend framework

• AWS Amplify's way of doing things (CLI, libraries, and patterns)

• AWS CDK

• TypeScript

Not just that but what often gets overlooked, is knowing when to use those tools.

Looking back, I put out a lot of tutorials that talked about how to build Complicated App™️ and the solution was filled with various workarounds to what should have been a simple process.

I forgot that most developers don't have direct access to an AWS engineering team. That most don't get a perpetually free AWS account to work in. And that most don't know when an enhanced experience is just around the corner so they shouldn't invest in hackySolution™️.

🗒️ One of my greatest realizations at AWS was when the director of our org spoke on the value of DA's by saying, "They [engineers] often will perform the workarounds without realizing that they're workarounds."

Nothing against our amazing engineers of course. His statement was simply about the impact of DA's being an important link the chain. Between our customers and product.

I had become Icarus. Through my various solutions and content pieces, I flew high without realizing I was advocating for the product instead of the developers I was trying to help. And with each YouTube video that showed what was possible, my wings melted in the sun of what I thought was good enough.

Switching teams and going in on AWS

Soon after, my personal interests shifted towards learning AWS services and I switched to the AWS AppSync team.

This is where I learned how to use the AWS CDK. I no longer had the luxury (and it is a luxury!) of letting Amplify do all the work in creating an API, adding authentication, or configuring a database. I also had to learn how to connect my frontend (NextJS) with my CDK backend.

It took months of learning and I'm fortunate my manager trusted me to figure out a DX that met my high bar.

I finally settled on a solution that worked well for the majority of small to medium-sized applications, and provided enough inspiration for medium to large applications.

My pitch to fullstack cloud developers was, "I'm trying to make your life 15% harder for unlimited flexibility".

Looking back, that pitch was pretty awful 😅

For context, this was when Supabase, SST, Vercel, and tRPC captivated crowds on what an amazing DX could look like. My solution works -- and many customers find success/inspiration from it, but it was a heavy sell for those outside of the niche.

So there I was. A DA no longer directly tied to the Amplify team or it's crowd of frontend developers. However, in building out fullstack applications, I wanted more flexibility than what Amplify had at the time, and I wanted frontend developers to have an easier onboarding than what the AWS CDK offers.

🗒️ I hate to keep stressing this, but the Amplify CLI can get you really far. And the AWS CDK is my favorite IaC tool.

https://www.youtube.com/playlist?list=PLiLHsu3XjGfMgGxbjK59tgGt0NYywpcDd

Enter Amplify Gen2

The amazing thing about AWS is that our teams (the ones I interact with) are structured like a startup -- albeit a well funded one. What I mean is that we never really rest on good enough. We are always challenging each other and Thinking Big.

So when my colleague and mentor René Brandel asked for my feedback on an API concept for Amplify, I took a look not expecting much of it.

One of our personal rules is that we don't do "company speak" or put fluff between the lines. We just say what we feel. So if something sucks, then we say it sucks and not stumble for the politically correct way of saying it. I encourage everyone to have a friend like this at work.

His solution sucked.

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

// a wordsearch API
const schema = a.schema({
    WordSearch: a
        .model({ // a database
            id: a.id().required(),
            name: a.string().required(),
            columns: a.integer().required(),
            rows: a.integer().required(),
            wordBank: a.string().array().required(),
        })
        .authorization([a.allow.owner()]), // an auth rule
})

It was all TypeScript based. There was no clear separation for when the frontend started and the backend began. The API was completely changed from what I was familiar with, and his presentation was filled with "what ifs", and "now imagine if you could"s.

I gave him my feedback on there being too much magic, how it changed how things were done, and how the problems customers faced when building applications would be the same and moved on with my day.

A few days later we met again to cover some minor changes he made. I remember telling him, "The API just doesn't look or feel like GraphQL". I'll never forget his reply:

"Who said this is GraphQL?"

Granted, it was GraphQL -- AppSync specifically. I knew that. But I only knew it because I was close to the product/engineering team. I realized I was being an Icarus -- flying high advocating for a product instead of what fullstack developers want.

🗒️ In hindsight, his idea didn't suck. I just couldn't hit pause on what I was familiar with long enough to see the benefits of what was in front of me.

He sent an early build for me to play around with and provide more feedback on, and this was in fact our cycle for the next several months.

In the end, thanks to him and the his team's engineering efforts, Amplify Gen 2 (preview) was announced during the re:invent 2023 season.

Admittedly, it wasn't until recently that I began trying to move my NextJS + CDK applications over to Amplify Gen 2. Most recently, this wordsearch app built with the CDK being ported over to this one using Gen 2 :

Amplify Gen 2 Takeaways

The rule I have with René is the same rule I have with all of you -- no fluff.

Amplify Gen 2 is nice...not perfect...but very nice!

Frontend Developers

From a frontend DX perspective, everything is in TypeScript. If you want to setup authentication, you do so using TypeScript. If you want to create an data resource (API), it's done in TypeScript as shown above.

This end-to-end type-safety is visible throughout the application. In a NextJS application for example, all of your CRUD operations are now fully-typed.

This means less context-switching and mental overhead. In 2024, it's all but expected, but a nice DX with nonetheless.

Backend Developers

For backend developers, the DX is even better IMO.

This may have flown under the radar for most people, but a big PR was merged in the CDK last year that the Amplify team was able to capitalize on: Making GraphQL schemas hot-swappable.

This means whenever a schema is changed, the running process would redeploy those assets to AWS. In relatable terms, this means when a customer runs the following command:

npx amplify sandbox

Then a stack (completely separated from your team/org) will get deployed and this process will watch for changes. When Amplify detects a change to your data file, for example, then it will redeploy your API, and run codegen on your behalf so that your get live feedback across your application.

🗒️ Much like the cdk watch command, sandbox environments are used during development.

Simple CRUD apps are great to showcase because they cover common scenarios. However, it's important to remember real-world applications are often much more involved. For example, adding AI generated content often needs another service or custom ability.

In the CDK, a custom mutation that called out to Amazon Bedrock would look like this:

type Mutation {
    generateWordSearchWords(theme: String!): String!
}

While simple at first, it's important to remember you still have to create the HTTP datasource:

// add bedrock as a datasource
const bedrockDataSource = api.addHttpDataSource(
    'bedrockDS',
    'https://bedrock-runtime.us-east-1.amazonaws.com',
    {
        authorizationConfig: {
            signingRegion: 'us-east-1',
            signingServiceName: 'bedrock',
        },
    }
)

Then give the datasource permissions to invoke the foundation model (Claude V2 in this case):

// Allow datasource to invoke claude
bedrockDataSource.grantPrincipal.addToPrincipalPolicy(
    new PolicyStatement({
        resources: [
            'arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-v2',
        ],
        actions: ['bedrock:InvokeModel'],
    })
)

Create and configure the custom resolver for your API:

// create a unit resolver that connects to bedrock and returns a string of words
const generateWordSearchWordsResolver = api.addResolver(
    'generateWordSearchWordsResolver',
    {
        dataSource: bedrockDataSource,
        typeName: 'Mutation',
        fieldName: 'generateWordSearchWords',
        code: Code.fromAsset(path.join(__dirname, 'generateWordSearchWords.js')),
        runtime: FunctionRuntime.JS_1_0_0,
    }
)

And only then can you write your business logic for your application:

export function request(ctx) {
    const assistant = ``
    const theme = ctx.args.theme
    const prompt = `Generate 10 words related to ${theme}. Put the words in an array. For example, if the theme was "animals", you would return ["monkey", "tiger", "bear", "lion", "gorilla", "bird", "penguin", "dolphin", "wolf", "dog"].`

    return {
        resourcePath: '/model/anthropic.claude-v2/invoke',
        method: 'POST',
        params: {
            headers: {
                'Content-Type': 'application/json',
            },
            body: {
                prompt: `\n\nHuman:${prompt}\n\nAssistant:${assistant}`,
                max_tokens_to_sample: 300,
                temperature: 0.5,
                top_k: 250,
                top_p: 1,
                stop_sequences: ['\\n\\nHuman:'],
            },
        },
    }
}

export function response(ctx) {
    console.log('the bedrock response', ctx.result.body)
    return ctx.result.body
}

In a TypeScript environment powered by Amplify Gen 2, this becomes much easier:

🗒️ You still have to assign the correct permissions, and your custom business logic is still up to you to decide.

What I love about this model isn't just the type-safety, but that I am able to copy over the permissions from the CDK project because at the end of the day, it's all TypeScript.

I love frontend frameworks that use APIs and concepts from browsers and push developers to MDN. Amplify does the same by taking care of the expected and telling customers that want additional services to view the CDK docs.

Continuity

Amplify Gen 2 in your CLI and code editor also brings enhancements to the Hosting platform as well! For starters, it's now possible to have wildcard subdomains on your domain name. This, along with enhanced server-side rendering support means it's now possible to have true multi-tenant applications hosted on Amplify.

Additionally, because of the closer connection to the CDK, Amplify will cdk bootstrap your account/region on your behalf!

Also, for teams that may incrementally adopt Amplify, have a large team, or have an existing CDK backend, it's possible to keep the applications separated while taking advantage of all the Amplify goodness.

Conclusion

A major part of developer advocacy is what my manager calls "selling what's on the truck". Meaning there are times when we know a big feature release is coming, but we have to help the folks that are trying to build today.

I'm happy with the current state of Amplify Gen 2, but any DX will need constant refinement. Myself and the team will continue to make improvements -- but we can only do it with your feedback.

My hope is that I gave you a glimpse into what it took to get t o this point, and inspired you to build with Amplify Gen 2 on your next project!

As always, let me know if you have any questions by hitting me up on X or LinkedIn.

Until next time,

Happy Coding 🦦

🗒️ I'm not anti-Lambda, I'm pro the-right-tool-for-the-job 😉 If simply passing data around while transforming it, using a Lambda function seem like the wrong tool

👆This post is a mix of the above 2 minute video and the two GitHub repos!

Configuring AppSync to pass data to EventBridge

In hindsight, I may have downplayed the power of EventBridge and AppSync by using localhost:3000 in my demo. In truth, real-time subscriptions can scale beyond 3M events per second.

However the principle is the same: Application 1 is a normal app, doing normal things. Then one day Application 2 decides they want to display that data in real-time. No polling, no sharing of resources, just taking an event and passing along the data associated with it.

It's possible for Application 1 to simple invoke an API endpoint provided by Application 2. But they are coupled. Any changes on either side and there needs to be communication. In an event-driven world, this becomes a non-issue. Application 1 would simply put a message on an event bus. It doesn't know or care what downstream services pick it up.

This scenario is exactly what the first repository does.

As mentioned earlier, AWS AppSync has direct support for Amazon EventBridge as a datasource. That means all the SigV2 signing it handled for you with one line of code:

const eventBridgeDS = api.addEventBridgeDataSource('gameBusDS', bus)

Now this simply forms the connection, however the function that passes the data is also fairly trivial:

export function request(ctx: Context): PutEventsRequest {
    // The data that gets sent to EventBridge
    return {
        operation: 'PutEvents',
        events: [
            {
                source: ctx.stash.eventBridgeSource,
                detailType: ctx.stash.eventBridgeDetailType,
                detail: { ...ctx.prev.result },
            },
        ],
    }
}

export function response(ctx: Context) {
    //Return the data from EventBridge back to AppSync
    return ctx.prev.result
}

Understanding EventBridge rules and targets

Passing an event to an event bus does effectively nothing. Consumers (targets) subscribe to rules on that event bus. The rule looks at the incoming event payload and says, "based on this matching criteria, I will invoke these targets".

From the diagram, we can see that an EventBridge bus has a rule setup that will call an AppSync API.

In the second repo, the code that configures this is as follows:

const mybroadcastRule = new events.CfnRule(scope, 'cfnRule', {
    eventBusName: bus.eventBusName,
    name: 'broadcastToAppSyncRule',
    eventPattern: {
        source: ['game.broadcast'],
        ['detail-type']: ['GameUpdated'],
    },
    targets: [
       //The targets that care about this message
    ]
})

Note the eventPattern object. This rule will invoke the targets if the incoming event payload has game.broadcast as the source and GameUpdated as the detail-type.

The next part of this repo is likely where--if you're like me, you'll make the most small-and-hard-to-detect errors:

Adding the target.

This is because we're using the L1 construct, so there aren't any utilities for better mapping EventBridge data to an AppSync operation. You get intellisense, but as someone who is used to working with L2 constructs primarily, feeling something to be desired.

targets: [
    {
        id: 'appsyncBroadcastReceiver',
        arn: props.appsyncEndpointArn,
        roleArn: ebRuleRole.roleArn,
        appSyncParameters: {
            graphQlOperation: props.graphQlOperation,
        },
        inputTransformer: {
            inputPathsMap: {
                createdAt: '$.detail.createdAt',
                updatedAt: '$.detail.updatedAt',
                name: '$.detail.name',
                homeTeamScore: '$.detail.homeTeamScore',
                awayTeamScore: '$.detail.awayTeamScore',
                currentMessage: '$.detail.currentMessage',
                id: '$.detail.id',
            },
            inputTemplate: JSON.stringify({
                input: {
                    createdAt: '<createdAt>',
                    updatedAt: '<updatedAt>',
                    name: '<name>',
                    homeTeamScore: '<homeTeamScore>',
                    awayTeamScore: '<awayTeamScore>',
                    currentMessage: '<currentMessage>',
                    id: '<id>',
                },
            }),
        },
    },
],

The first 3 lines should make sense. The 4th line is where we pass in the AppSync operation we're working with.

🗒️ Running npx @aws-amplify/cli codegen add in a directory that contains the schema.graphql file will generate the needed types for you.

However, the focus is on the inputPathsMap and the inputTemplate.

Understanding the EventBridge InputPathsMap

As someone who doesn't often work with EventBridge, I'll do my best here.

Essentially, a EventBridge payload is an object of whatever depth. I imagine some are deeply nested. Furthermore, EventBridge doesn't care about what data a target needs. As such, the inputPathsMap is your chance to flatten the data and pull out just the values you need.

Similar to how a Lambda function has event or AppSync has context, EventBridge rules put the data under "$". So the event source is "$.source" while all the arguments that we passed in are under "$.detail".

Understanding the EventBridge InputTemplate

The inputTemplate works in conjunction with the inputPathsMap. If the latter lets us pull out the values we need, then the former allows us to structure it however we like.

Again, an EventBridge rule has no idea how we need our data structured, so it's up to us to tell it.

🗒️ This isn't entirely true. In my testing, when I put in the wrong structure for my AppSync input and tried to deploy, my deploy would fail while performing some validation on my behalf.

It's worth noting that the inputTemplate is a string. It's also good to see that the input object is only there because our AppSync schema has an input field for the publishMsgFromEB Mutation.

Conclusion

These two separate apps form the basis of connecting real-time applications together without them being inherently coupled. Event-driven architectures is a big topic, and I hope this helped you understand just how powerful-yet-approachable it can be when using the AWS CDK to provision your services.

I'm curious to hear your thoughts on this! Let me know in the comments.

Until next time,

Happy Coding 🦦

Fortunately, the release of Hashnode's headless UI makes this all possible.

This post will focus on my journey enabling the Hashnode Starter Kit to run on AWS Amplify, why I decoupled it from its monorepo setup, and what my plans are for the future of my blog.

Where standard Hashnode fell short

Hashnode has done an excellent job at delivering incremental value. I remember when it was just blogging. Then custom domains launched, followed by custom CSS. Each iteration felt like it was from the voice of their audience while technical details were made public for folks to learn from.

However, my needs were diverging from the the platforms core audience. I didn't want another AI tool to offer over embellished ways of writing. I wanted to insert sponsor links. I wanted a customized Focus Otter store that integrated with Stripe, and if I'm being honest, I felt the newsletter experience offered by Hashnode was too limiting for what I'd like to put out to the audience.

At the same time, my friend Allen Helton shared details around his custom blogging solution, so I migrated my blog to a custom setup using GitHub Pages and mimicked his setup.

I failed incredibly hard.

Allen's setup was customized to his needs, goals, and technical ability. It was the culmination of small improvements over time. So I tried to build my own custom setup and it went exactly as you might expect:

I felt stuck. What I wanted was a launch pad. A way to easily get a custom site up and running...but not too custom where I would spend days/weeks trying to make it my own. Well as always, Hashnode listened and as the author Mark Twain said,

"History doesn't repeat itself, but it often rhymes."

Hashnode had once again delivered a feature that felt straight from the voice of their audience.

Customizing the Headless UI Experience

A headless UI is a term used to describe a feature where backend functionality is given and exposed to the frontend via API's. For example, a React UI component that creates a table is nice, but probably limiting in how you can customize it. What's better, is to give developers all the tools, hooks, and methods to build their own table and they provide the UI themselves.

Hashnode does the same thing by providing 3 starter repos that come integrated with all the utility functions, API calls, etc for building out a Hashnode-like experience.

Using their GraphQL API, developers can craft queries that best match the UI experience they're trying to deliver.

However, there were a two problems I had with their setup.

1. It was tailored to Vercel

2. It was setup as a monorepo

The first one made sense in a way because the 3 starter themes offered (personal, hashnode, enterprise) are NextJS apps, but going back to my needs, I like the integration and customization offered by AWS Amplify. It provides full support for NextJS, while allowing me to build out custom solutions using serverless services

As for the second option, this is more of a personal gripe. The monorepo setup is made with pnpm, and while AWS Amplify has support for monorepos, I didn't fee like the Hashnode starter kit should be one, but rather standalone packages.

My reasoning is that if the goal is to deploy only one of the themes, then despite their being shared resources, the starter templates should live on their own with shared packages and styles in NPM packages. This is similar to how Vercel allows for prebuilt templates to be used.

Fortunately, deleting the packages for the monorepo and moving things into a single project repo was very straightforward. If wanting to view what that kind of repo looks like, I have a branch setup that you can take a peek at:

🗒️ The great thing about this setup, is that it's just a NextJS app using the pages directory and SSG. This means it can be deployed anywhere.

Setting up my project on AWS Amplify

Gone are the days of uploading a project to an S3 bucket, setting up a Cloudfront distribution, and creating a hosted zone in Route53 just to get a site up on the web using AWS.

As you'd come to expect, you just tell Amplify which Git provider you're using (GitHub), which repo you'd like to upload, and it does the work for you.

Because I purchases my domain on AWS, setting up a subdomain was as simple as writing blog.

This is great because I already use Linktree with Amplify to setup a custom domain for focusotter.com

From there, the only thing left to go to Hashnode and tell it to enable headless UI mode.

This setup allows me to write my blogs using Hashnode's amazing CMS, schedule them, view analytics, and more, while still having complete control over what the user sees and experiences on my site.

Where I plan on taking my blog

At the time of this writing, I still have the base enterprise starter plan. The "Book a demo" link doesn't do anything and the newsletter doesn't go anywhere.

However, it will now be very easy to customize this experience to my personal needs. A few things I'll be adding in the short term:

1. Audio Blogs: Hashnode removed this feature due to non-usage, but I would love to bring this back!

2. Translations: I'd love to use the power of AWS to automatically translate my site into a language that best suits the reader.

3. Store front: Folks often ask me where they can get Focus Otter apparel and swag. It's coming soon! 🦦

4. Premium blog posts: Converting my blog into a SaaS product where users can signup, and select a very small donation plan to get access to premium blog posts is something I've been wanting to add for a while.

5. Much more!

Conclusion

This post showed you how I setup my blog with a custom domain on AWS Amplify while still having it backed by Hashnode's headless UI.

But that wasn't really the point.

I want to highlight what's possible when a company genuinely strives to make life simpler for its users while still allowing them to creatively expand on what they've built.

Hashnode does this very well and for that, I look forward to blogging with them for many years to come.

-- Focus Otter 🦦

1. Manually signing SigV4 requests

2. The coupling between the application that sent the request, and the application that consumed it.

Fortunately, that all changed when EventBridge announced the addition of AWS AppSync as a direct target🎉

In this post, I'll show how to build out this integration from the position of an event that just got sent to an EventBridge bus. We'll use the AWS CDK to construct this, and show how to test the sample.

🗒️ The code for this blog post can be found here:

https://github.com/focusOtter/eventbridge-target-appsync

Project Overview

The repo has all the code, and the readme is detailed, so I'll be going over the services in more detail.

Amazon EventBridge

When building out API's there's a subtly contract made between the creator and the consumer. That is: Whenever the creator makes a change, the consumer needs to update to meet that change.

A message bus solves this by serving as an intermediary between the two. Put simply, when application events happen on application 1 like "An order is placed", instead of calling the RewardsAPI , and FulfillmentAPI, a message is put on the message bus:

🗣️ "Hey, order abc123 was placed "

Now, those downstream teams can grab that event and do whatever they want. Teams do this by setting a matching criteria on the event:

"If the message has the word order in it."

On AWS, the bus is called EventBridge, and the matching criteria is an EventBridge Rule. Those downstream services are called targets.

AWS AppSync

Ok, I have recorded, streamed, and written a lot of content around AppSync. So definitely checkout my channel and previous blogs to get up to speed.

Application Overview

The application in the provided repository uses the AWS CDK to create and provision the mentioned services. The CDK allows us to write TypeScript to version our services instead of clicking through the AWS Console.

const appName = 'eventbridge-to-appsync'

const auth = createCognitoAuth(this, { appName })

const api = createAppSyncAPI(this, { appName, userpool: auth.userPool })

const cfnAPI = api.node.defaultChild as CfnGraphQLApi

const eventBridge = createEventBridge(this, {
    busName: 'eb-appsync-bus',
    appsyncApiArn: api.arn,
    appsyncEndpointArn: cfnAPI.attrGraphQlEndpointArn,
    graphQlOperation: publishMsgFromEB,
})

When it comes to creating the AppSync API, there are one main point of interest:

Schema Definition

type Mutation {
    publishMsgFromEB(msg: String!): String! @aws_iam
}

type Subscription {
    onPublishMsgFromEb: String
        @aws_cognito_user_pools
        @aws_subscribe(mutations: ["publishMsgFromEB"])
}

This tells AppSync to protect the publishMsgFromEB mutation with IAM permissions, and that consumers can subscribe to that mutation if they are in a Cognito user pool.

However, the focus is really the EventBridge rule. This forms the connection between the EventBridge bus and the target (AppSync):

const mycfnRule = new events.CfnRule(scope, 'cfnRule', {
        eventBusName: bus.eventBusName,
        name: 'mycfnRule',
        eventPattern: {
            source: ['sample.source'],
        },
        targets: [
            {
                id: 'myAppsyncTarget',
                arn: props.appsyncEndpointArn,
                roleArn: ebRuleRole.roleArn,
                appSyncParameters: {
                    graphQlOperation: props.graphQlOperation,
                },
                inputTransformer: {
                    inputPathsMap: {
                        msg: '$.detail.msg',
                    },
                    inputTemplate: JSON.stringify({
                        msg: '<msg>',
                    }),
                },
            },
        ],
    })

This is the L1 construct for creating a rule. It specifically listens for the sample.source source on the event payload and invokes our AppSync API in response.

Conclusion

For detailed instructions on how to test this event, refer to the readme in the repository! In the end, this new integration unlocks a new streamlined approach to creating real-time, event-driven applications that are decoupled from one another.

I'll be posting a bunch more on what you this unlocks so stay tuned for more to come, until then,

Happy coding🦦

In this post, I'll show you how to securely combine a NextJS frontend with an AWS CDK backend. By the end of this post, I hope you see that the parts that I found scary, are nothing more than simple access patterns.

This post now has a YouTube video with it that shows a full project walkthrough!

Project Setup

Like a medium-rare steak and a good cabernet, this post is best paired with a GitHub repo 👇🏽

The repo has all the setup code, and deployment instructions. So instead of repeating that information, I'll instead elaborate on the following sections:

1. Authentication with Amazon Cognito

2. Creating an S3 Bucket with IAM permissions

Authentication with Amazon Cognito

Amazon Cognito is a 3-headed service from AWS. It's made up of the following parts:

1. Userpools: As the name suggests, when a user signs up this is where they go

2. Userpool Client: Sometimes you need to provide callback or logout redirect details for social authentication. That's what a client is for.

3. Identity Pool: If a userpool is where our users go, an identity pool manages what they can do. This distinction is important.

In the _backend/lib/auth/cognito.ts file from the repo, I setup these 3 pieces of Cognito. What I love about this file is that's 100% boilerplate. Sure I can tweak whether or not a user's email address is their username or if they need to provide a phone number, but typically, I just borrow this file from project to project.

\>🗒️ This project doesn't make use of the Userpool Client, again, I just keep it around to make my life easier if I need it.

The identity pool is the star of the show:

const identityPool = new IdentityPool(
  scope,
  `${props.appName}-identitypool`,
  {
    identityPoolName: `${props.appName}-identitypool`,
    allowUnauthenticatedIdentities: true,
    authenticationProviders: {
      userPools: [
        new UserPoolAuthenticationProvider({
          userPool: userPool,
          userPoolClient: userPoolClient,
        }),
      ],
    },
  }
)

Primarily because with it, we get access to an authenticatedRole and unAuthenticatedRole.

We can assign permissions to these roles so that when a user comes to our site, they can assume one of these roles.

One the frontend, we make use of Cognito with the following line:

export default withAuthenticator(Home, { signUpAttributes: ['email'] })

The two sides of Amazon S3: Creation and Permission

An S3 bucket is a where we can put a bunch of files. Creating an S3 bucket is one of the easiest things to do with the AWS CDK:

const fileStorageBucket = new s3.Bucket(scope, `updownBucket`)

This is all that's needed to create it. From here, we now have to manage the permissions for it.

Fortunately, it's also a fairly boilerplate process.

As you can see in the lib/storage/uploadDownloadBucket.ts file, if you want to enable CORS, the bucket then becomes the following:

const fileStorageBucket = new s3.Bucket(scope, `updownBucket`, {
    cors: [
        {
            allowedMethods: [
                s3.HttpMethods.POST,
                s3.HttpMethods.PUT,
                s3.HttpMethods.GET,
                s3.HttpMethods.DELETE,
                s3.HttpMethods.HEAD,
            ],
            allowedOrigins: ['*'],
            allowedHeaders: ['*'],
            exposedHeaders: [
                'x-amz-server-side-encryption',
                'x-amz-request-id',
                'x-amz-id-2',
                'ETag',
            ],
        },
    ],
})

🗒️ The exposedHeaders array is good hygiene as it makes it easier to debug S3 specific errors. Copy Pasta 🍝

From that, we have an S3 bucket is can be called from the frontend. However, this still doesn't answer the question of who has the permission to call it from the frontend.

Amazon S3 bucket permissions are governed by policies. These policies are then given to a role that someone or some other service can assume.

Let's breakdown what that means:

// Let signed in users Upload on their own objects in a protected directory
const canUpdateAndReadFromOwnProtectedDirectory = new iam.PolicyStatement({
    effect: iam.Effect.ALLOW,
    actions: ['s3:PutObject', 's3:GetObject'],
    resources: [
        `arn:aws:s3:::${fileStorageBucket.bucketName}/protected/\${cognito-identity.amazonaws.com:sub}/*`,
    ],
})

This policy allows the ability to PUT and object in S3 and GET an object from s3. Which S3 bucket? Which part of the S3 bucket? Well, that's where the resource comes in play.

This policy verify specifically allows access to any file (*) in the /protected/{cognito-identityId} of the bucket we created.

Now this is just a policy. Someone/some service has to have it (aka assume it). For that, we tie a role and a policy together:

new iam.ManagedPolicy(scope, 'SignedInUserManagedPolicy-test', {
        description:
            'managed Policy to allow upload access to s3 bucket by signed in users.',
        statements: [canUpdateAndReadFromOwnProtectedDirectory],
        roles: [props.authenticatedRole],
    })

On the frontend, we make use of our S3 bucket with the following two components:

Uploading

<StorageManager
  acceptedFileTypes={['image/*']}
  accessLevel="protected"
  maxFileCount={1}
  onUploadSuccess={({ key }) => {
    setFilename(key as string)
  }}
/>

Downloading

<StorageImage
  alt={fileName}
  imgKey={fileName}
  accessLevel="protected"
/>

🗒️ For both of those UI components, notice how I'm passing in the protected string. This will not only store the file name in my bucket, but under the protected/{cognito-identityId} path as well!

Conclusion

It's worth noting that what I did in this project can be done even easier with the Amplify CLI, however by managing my own resources with the CDK, I can have full control over the policy process and even add on additional configurations that may not be offered by the Amplify CLI such as cacheing my images with a CDN:

Trading convenience for control is a line that takes practice to get right, but as your applications before more complex the right decision becomes more apparent.

Let me know in the comments if this helped you understand AWS permissions, or if there's anything specific you'd like to see!

Happy coding 🦦

In another use case, I want to create an AI-generated bedtime story for my kids. When it comes to creating the image, audio, and story, these things take time. Instead of polling, I'd like to be notified when it's done.

Both of those scenarios are examples where you'd want to call AppSync from a Lambda function and what the focus of this post is about.

📹 This post now has a full video guide!

https://youtu.be/-qogqNXlDKM

🗒️ I provided a repo above incase you want to get straight to the good bits!

If you're familiar with Lambda functions but new to AWS AppSync, no worries, I have the video for you!

NodeJS Lambda Functions in the AWS CDK

Fortunately, when it comes to the AWS CDK and Lambda functions, we have the ability to create our resources in TypeScript. From the readme, this is how we create the Lambda function:

export const createInvokeAppSyncFunc = (
    scope: Construct,
    props: InvokeAppSyncFuncProps
) => {
    const invokeAppSyncFunc = new NodejsFunction(
        scope,
        `${props.appName}-invokeAppSyncFunc`,
        {
            functionName: `${props.appName}-invokeAppSyncFunc`,
            runtime: Runtime.NODEJS_18_X,
            handler: 'handler',
            entry: path.join(__dirname, `./main.ts`),
        }
    )

    return invokeAppSyncFunc
}

Note that aside from some props being passed in, the core is essentially giving it a name, a runtime, and pointing it to the file location.

How to allow Lambda to Sign with SigV4

This file sucks. I wish it were easier (now it is!). The good news is that you never have to modify it. There are some NPM packages out there that allow you to install it, but it's simple enough to just paste in a project.

Let's break it down:

import { SignatureV4 } from '@aws-sdk/signature-v4'
import { Sha256 } from '@aws-crypto/sha256-js'
import { defaultProvider } from '@aws-sdk/credential-provider-node'
import { HttpRequest } from '@aws-sdk/protocol-http'
import { default as fetch, Request } from 'node-fetch'

Those imports are needed because the @aws-sdk v3 takes a modular approach. So every bit and piece comes from a standalone package.

Next, we have the following:

// deconstruct the url and create a URL object
const endpoint = new URL(params.config.url)

// create something that knows how to let Lambda sign AppSync requests
const signer = new SignatureV4({
    credentials: defaultProvider(),
    region: params.config.region,
    service: 'appsync',
    sha256: Sha256,
})

Not too bad 😄 This parses the AppSync GraphQL endpoint in an object containing it's various pieces (protocol, pathname, etc).

In addition, we create a signer by passing in details relating to what we're trying to sign. Sigv4 is similar to creating a JWT or hashing a password in my opinion. Not from a cryptography standpoint, but from a "Hey, I'm going to pass you stuff, and you do all the hard work for me" standpoint.

From there, we keep it going by taking that signing mechanism and passing it the request we are trying to sign:

// Setup the request that we are wanting to sign  with our URL and signer
const requestToBeSigned = new HttpRequest({
    hostname: endpoint.host,
    port: 443,
    path: endpoint.pathname,
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        host: endpoint.host,
    },
    body: JSON.stringify(params.operation),
})

// Actually sign the request
const signedRequest = await signer.sign(requestToBeSigned)

// Create an authenticated request for fetch
const request = new Request(endpoint, signedRequest)

With all that in place, we now have a request that is signed, sealed and in the try/catch block, delivered!

Usage

In the main.ts file, we actually use the AppSyncRequestIAM helper method by invoking it with our AppSync operation:

 const res = await AppSyncRequestIAM({
  config: {
    region: process.env.REGION as string,
    url: process.env.APPSYNC_API_URL as string,
  },
  operation: {
    operationName: 'BroadcastMessage',
    query: broadcastMessage,
    variables: {
      msg: event.msg,
    } as BroadcastMessageMutationVariables,
  },
})

Note that this only pertains to signing the request. It will never get this far to begin with if the following isn't enabled:

1. The AppSync API doesn't have IAM authorization enabled

2. The Schema doesn't have the @aws_iam directive listed on the operation

3. The Lambda was never given persmissions to invoke AppSync (api.grantMutation(invokeAppSyncFunc)

Conclusion

Calling AppSync from a Lambda function--or any out-of-band service, requires IAM permissions. This can be tricky, especially the first time. But I hope this post showed you just how simple things can be when you understand the moving pieces.

What are some use cases you'd like to see covered? Let me know in the comments or on social media.

Until then, Happy Coding 🦦

This post has a YouTube companion! You can check it out here or continue reading 🦦

Have you ever found yourself in a situation and thought, "We're in 2024, and we're still doing it this way?".

My neighborhood sold paper tickets so that strangers could come in and see the home decorations. I volunteered to have my home as a tour stop because it sounded like a way to meet new people in the area.

What I didn't realize until the day of was that all the tickets were the same. There was no tracking process. They were just paper tickets handed out after paying through Venmo. Furthermore, the tickets weren't collected or redeemed.

So I came up with a solution where someone could purchase a ticket online and have it texted to them. The ticket would contain a unique code, and their name.

This post will focus on the ticket generation aspect!

If wanting to skip to trying this out on your own, I have an entire repo that you can use. Follow the readme to get started and begin making your own tickets!

Choosing a ticket template

Our goal is to turn the following image:

Into a template that we can make our own:

For that, I went to Canva and simply typed "Holiday ticket". From there I tweaked it until I was satisfied, making sure to leave space on the right-hand side for a QR-Code/Barcode, and in the center for the name.

Project Setup

We'll do all this locally for now. As mentioned, in later posts, we'll see how to automate the ticket distribution process and trigger it from a successful payment.

Inside a new project folder, run the following command from your terminal:

npm i bwip-js sharp text-to-svg

• bwip-js: Used to create SVG, Buffer, Barcodes, and QR Codes in code

• sharp: Super popular image manipulation library, known for its speed and ease-of-use

• text-to-svg: A dependency-less way to create turn text strings into an SVG

With these packages installed, create an index.mjs file and paste in the following imports and variables:

import sharp from 'sharp'
import * as path from 'path'
import bwipjs from 'bwip-js'
import { fileURLToPath } from 'url'
import TextToSVG from 'text-to-svg'

const __filename = fileURLToPath(import.meta.url)
const __dirname = path.dirname(__filename)

When using .mjs file extensions, the __dirname variable isn't available. To mimic this behavior we create our on using the fileURLToPath method.

Next, ensure the templated image you created from Canva is in the root of your directory.

Lastly, create a folder where you would like to have the newly created image saved. This will be in your project's directory, but feel free to call it whatever you like. For me, I'm creating an output/event/holiday-walkthrough folder path.

When all done, your file tree should look similar to the following:

Creating an SVG from text

A text string, is different from a text image. While we may look at text on an image and think "Oh, it's just text". Making the distinction upfront helps us think in layers.

Fortunately, the text-to-svg package will do all the work for us.

Paste in the following code in your index.mjs file:

// Create an SVG from text
async function generateSVG(text) {
  const textToSVG = TextToSVG.loadSync()
    try {
        const svg = textToSVG.getSVG(text, {
            fontSize: 110,
            anchor: 'top',
            attributes: { fill: 'black' },
        })
        return Buffer.from(svg)
    } catch (err) {
        console.error('Error generating SVG:', err)
        throw err
    }
}

This function is broken up into 3 main parts:

1. Instantiating textToSVG . The loadSync function optionally takes in a font path, but more on that in a future post 😉

2. Creating the SVG from text. Nothing too crazy here. We give it a font size, an anchor point, and a color. The docs for this package are really helpful, so feel free to play around with the attributes.

3. Returning an SVG buffer. Large amounts of text are best held as a buffer. This is just an in-memory way to contain large amounts of data. Similar to a variable, but for complex data-types like images.

Creating a QR Code and Barcode in NodeJS

The bwipjs library is fantastic. Really easy to work with and well documented!

Using this library, and a similar approach to creating an SVG of text, I was able to create both a barcode and QR Code without much issue.

To do the same, paste in the following bits of code:

// Create a QRCode
async function generateQRCode(text) {
    let qrcodeBuffer = await bwipjs.toBuffer({
        bcid: 'qrcode',
        text,
        scale: 5,
    })

    return qrcodeBuffer
}

// Create a Barcode
async function generateBarcode(text) {
    let svg = bwipjs.toSVG({
        bcid: 'code128', // Barcode type
        text, // Text to encode
        width: 80,
        // includetext: true, // Show human-readable text
        textxalign: 'center', // Always good to set this
        textcolor: 'ff0000', // Red text
        rotate: 'L',
    })
    return Buffer.from(svg)
}

Aside from a few attribute differences, the key points are there: Create a buffer and setup some attributes.

I scaled up the QRCode to 5 because it was a little small by default, but again feel free to play around with that.

For the barcode, I set the bcid to code128 based on the docs, but I don't know enough about barcodes to know if this is optimal or not🤷🏽‍♂️

Generating an image using the Sharp library

We have functions to create image buffers, but we need to but that data onto our image template. This is where the sharp library comes in.

It's worth noting that the sharp library can do a lot! We're only using a small portion of it, but essentially any manipulation of images can be done with this package.

Let's get started by creating a function to create the ticket for us. Paste in the following code:

async function createTicket(customerName, ticketId, outputPath) {
    const ticketTemplatePath = path.join(
        __dirname,
        './xmas-sample-ticket-hi-res.png'
    )

    const ticket = sharp(ticketTemplatePath)
}

The function above will take in the params needed to generate a dynamic ticket and is aware of wher to save it. Inside the function, we create the full path of the ticket template and pass it to sharp. The ticket variable is now a sharp instance. Any operations or manipulations we perform on the ticket variable will correspond to the ticket template itself.

To demonstrate that, let's create a try/catch block that will call our generate functions. Paste in the following code:

try {
    // Generate  barcode for the ticket as buffer
    const barcodeImageBuffer = await generateBarcode(ticketId)

    // Generate customer name for ticket as buffer
    const customerNameImageBuffer = await generateSVG(customerName)

    const qrcodeImageBuffer = await generateQRCode(ticketId)

}catch (err) {
    console.error('Error creating ticket:', err)
    throw err
}

This simple block will create buffers of our SVG. We'll pass these to our ticket variable (aka sharp). At the moment however, it doesn't know where to put them. To fix that, we'll create overlay objects that will have both the buffer, and the positions where each buffer should be.

To better understand that, paste in the following code inside the try-block:

// Params to overlay QR code onto the template
const qrCodeOverlay = {
  input: qrcodeImageBuffer,
  top: 494, // X position for QR code
  left: 3308,// Y position for QR code
}

const barcodeOverlay = {
  input: barcodeImageBuffer,
  left: 3393,
  top: 351, 
}

// Params to overlay SVG onto the template
const svgOverlay = {
  input: customerNameImageBuffer,
  top: 791,
  left: 508,
}

These overlay objects are exactly what sharp is expecting when composing images together.

🧐 "But Focus Otter, where did you get the values for the top and left keys?

Great question! I'm sure there's a smarter way, but for the sake of ease, I used Figma and it's ruler capabilities!

To show how this all comes together, the last part of this function is to use the composite function from sharp to take our images and turn them into one.

Paste in the following code underneath the overlay objects:

await ticket
  .composite([
    // barcodeOverlay,
    qrCodeOverlay,
    svgOverlay,
  ])
  .toFile(outputPath)

console.log('Ticket created!')

I commented out the barcodeOverlay since you probably don't want both a QR Code and a barcode, but feel free to uncomment!

That's it🎉 You now have a working solution

Testing the solution

To make sure this all works as expected, setup some test data and call the function. For me, I have the following:

// Example usage
const customerName = 'Focus Otter'
const hyphenatedCustomerName = customerName.toLowerCase().replace(' ', '-')
createTicket(
    customerName,
    'some-random-ticket-id',
    `output/event/holiday-walkthrough/${hyphenatedCustomerName}-ticket.png`
)

From there, in my terminal, I can run node index.mjs to create my ticket!

What I love about this project is how it can be taken into so many different directions. From simple automations with a CSV, to a full Micro-SaaS with Stripe and AWS (😉)

If you found this helpful, I'd love for you to let me know in the comments!

Until next time, Happy coding 🦦

During peak COVID, I was doing a lot of virtual events. To help, I created a demo where I played a live game of Connect4 with one of the attendees while talking about AWS Amplify

That talk was a lot of fun! However, once things started to open up, I wondered how I can bring that kind of engagement to my onstage presentations.

In this post, I'll show how I used Apple Keynote and AWS AppSync subscriptions to create an engaging presentation that included over 400 attendees at the same time!

Keynote Setup

Once upon a time, I would spend weeks developing slides in code so that I could get the developer fix I craved. This was more self-fulfilling than creating value for attendees. So I went back to Apple Keynote.

I prefer Keynote because of its modern-looking templates and features. But one day, I spotted another feature that got my gears turning:

export to html

Once exported, you're given a folder that contains an index.html file and an assets folder. The assets folder contains all of your slides--it isn't meant to be modified or easy to understand so for my purposes I left it as is and whenever I modified my slides I just re-exported.

The index.html however is more interesting.

What I love about this file is how simple it is. As for what I've learned from testing different scenarios, here ya go:

• The id in the body tag is needed so the slides know where to mount.

• Not everything nested in the body tag is needed, but it's best to just leave it alone.

• When viewed in the browser (via VS Code's liveServer feature or otherwise), the click event listener is hijacked and used to advance the slides. This is important to know for development purposes.

• The div.slideshowNavigator element is used to show a slide preview. To see them, move your cursor to the left side of the screen when viewing your slides in the browser.

Keynote to React

This part isn't novel but was definitely an "aha" moment.

I had the idea of overlaying emojis on my slides but wanted to take advantage of the React ecosystem to do so.

I'm sure there are ways to do this in [insert some modern framework], but since the easiest way to do this was to merge the Keynote HTML file with the HTML file of a React framework, I used Create React App.

npx create-react-app my-presentation && cd $_ && code .

From there, I merged the index.html file in create-react-app with the one generated from Keynote:

<!--public/index.html-->
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <meta name="theme-color" content="#000000" />
        <meta
            name="description"
            content="Web site created using create-react-app"
        />
        <link rel="apple-touch-icon" href="%PUBLIC_URL%/logo192.png" />
        <link rel="manifest" href="%PUBLIC_URL%/manifest.json" />
        <title>React App</title>
    </head>
    <body id="body" bgcolor="black">
        <noscript>You need to enable JavaScript to run this app.</noscript>
        <div id="root"></div>
        <div id="stageArea" style="z-index: -100">
            <div id="stage" class="stage"></div>
            <div id="hyperlinkPlane" class="stage"></div>
        </div>
        <div id="slideshowNavigator"></div>
        <div id="slideNumberControl"></div>
        <div id="slideNumberDisplay"></div>
        <div id="helpPlacard"></div>
        <div id="waitingIndicator"><div id="waitingSpinner"></div></div>
        <script src="assets/player/main.js"></script>
    </body>
</html>

In addition, I dragged the assets folder given from the Keynote output to the public directory in the React project so the script tag in the HTML file correctly points to it.

Congrats! You now have your slides as a React app! 🎉

Testing Interactivity with Framer Motion

The audience attendees will have a web app to add emojis, however for testing, it'll be nice to add a button. Whenever the button is hovered (because the click event is hijacked), we want an emoji to float up on the screen.

Let's first add Framer Motion by running the following command in your terminal:

npm i framer-motion

From there, add the following component to the App.js file alongside the one that is already there:

const EmojiThrower = ({ emoji = '💯' }) => {
    const randomX = Math.random() * (window.innerWidth - 100)
    return (
        <motion.div
            z-index={100}
            initial={{ y: '100vh', x: randomX, opacity: 1, position: 'absolute' }}
            animate={{ opacity: 0, y: 0 }}
            exit={{ opacity: 0 }}
            transition={{ duration: 2 }}
        >
            <p style={{ fontSize: '40px' }}>{emoji}</p>
        </motion.div>
    )
}

This is a component that displays an emoji (by default a 💯) at the bottom of the page (100vh) and a random place along the x-axis. Initially, the emoji is fully visible, but over two seconds it both decreases its opacity to zero and brings itself to the top of the screen (0px).

Next, update the App component so that it renders an EmojiThrower every time the button is moused over.

import { motion } from 'framer-motion'
import { useState } from 'react'

// ...EmojiThrower code

function App() {
    const [emote, setEmote] = useState([])
    const handleClick = () => { setEmote([...emote, 1])}

    return (
        <div className="App">
            <div style={
                { display: 'flex', justifyContent: 'flex-end' }
            }>
                <button onMouseOver={handleClick}>
                    Show Component
                </button>
            </div>
                {emote.map((item, i) => {
                    return <EmojiThrower key={i} />
                })}
        </div>
    )
}

export default App

Because the slideshowNavigator has a top z-index, the button we'll use for testing has to be moved to flex-end so that the onMouseOver event can fire.

Creating and hosting an app for your audience

Being able to click a button and show the emojis locally is nice for testing purposes, for live engagement, we'll need our attendees to click buttons on a deployed app instead.

No need to recreate the wheel here since I already have a repo that does just this 🙂

Fork (and star😉) the following repo and install its dependencies:

When running the project with npm run start, you should see a simple app:

In the code, the section to display emojis is handled by refs:

const emojiRef = useRef([
        { emoji: '🔥', displayText: '🔥 Fiya' },
        { emoji: '👍🏽', displayText: '👍🏽 This is great' },
        { emoji: '🦦', displayText: '🦦 Focus Ottered in!' },
        { emoji: '☁️', displayText: '☁️ Serverless Cloud' },
        { emoji: '👀', displayText: '👀 I see you!' },
        { emoji: '🌮', displayText: '🌮 Gimme moar!!' },
    ])

Feel free to change those to emojis that best suit your needs.

The next part of the code is the handleClick handler that fires whenever a user clicks a button:

const handleClick = async (emote) => {
        const reaction = {
            icon: emote,
        }
        const channel = 'miami'
        await gen.publish(channel, JSON.stringify(reaction))
    }

We'll publish data to a WebSocket channel. In my case, I was attending the amazing React Miami conference, so I named my channel miami. This doesn't actually matter much to us, but I like to update it in case I'm showing off the code.

The last part to discuss is the await gen.publish(channel, JSON.stringify(reaction)) line.

When we create our WebSocket API in AWS, it will provide a file called generated file for us. The forked repo came with this file. Essentially, it exports a function called publish that takes it a channel name, and a string of data. When invoked, it will publish the data to any clients subscribed to that channel.

With the main files in understood, feel free to host this simple web app wherever you like. I prefer to use AWS Amplify 🙂

Bringing the idea to life with AWS AppSync

This is usually the part where I provide a blurb about how AWS AppSync is a managed GraphQL service by AWS and talk about its benefits. But for this project, we're only interested in leveraging its WebSocket feature so we won't be diving it that.

If you are wanting to learn about that, however, I have a full tutorial for you to checkout:

Adding WebSockets to your application is really easy and one of the few times I recommend using the AWS Console instead of infrastructure as code.

On the AWS AppSync service page, select Get started with AWS AppSync.

This will prompt you to log into your AWS Account. Go ahead and sign in.

🗒️ If you logged in with your root account, or are new to AWS, be sure to check out my video to make sure your AWS account has basic security measures in place!

https://www.youtube.com/watch?v=UnqxiSJEZAk&t=10s

Once signed in, select the orange Create an API button. At this point, you should see a few options on how to create an API. Select Create a generic real-time API and click start as shown in the following screenshot.

Give your API a name (any name is fine). After selecting next, your new WebSocket API will be provisioned 🎉

Once done, the src/generated.js file in your presentation project should make more sense: AppSync generates the majority of the code. All we have to do is update the URL and API Key so that it matches our own API credentials.

In the settings tab on the left, copy your API URL and the API key and paste them in the generated.js file in both the emoji-thrower application, and the react-keynote application.

import { API, graphqlOperation } from 'aws-amplify'

export const config = {
    aws_appsync_graphqlEndpoint:
        'https://long-string.appsync-api.us-east-1.amazonaws.com/graphql',
    aws_appsync_region: 'us-east-1',
    aws_appsync_authenticationType: 'API_KEY',
    aws_appsync_apiKey: 'da2-bunch-of-alphanumerics',
}

With both projects having the correct AWS configuration, all that's left is to update our react-keynote project so that instead of manually firing the emoji on button hover, it listens for events from the EmojiThrower application.

Update the App component in the react-keynote app with the following:

import { subscribe } from './generated'
import { motion } from 'framer-motion'
import { useEffect, useState } from 'react'

// ...EmojiThrower component

function App() {
    const [emote, setEmote] = useState([])

// this is new
    useEffect(() => {
        const sub = subscribe('miami', ({ data }) => {
            console.log(data)
            const icon = JSON.parse(data).icon
            setEmote((prevState) => [...prevState, icon])
        })

        return () => {
            sub.unsubscribe()
        }
    }, [])

// no more <button/>
    return (
        <div className="App">
            {emote.map((item, i) => {
                return <EmojiThrower key={i} emoji={item} />
            })}
        </div>
    )
}

export default App

I did this live for AWS Developer Innovation Day and in the span of 3ish minutes, I handled over 5500 subscription requests!

It helps if you create a QR Code for your audience and add that to one of your slides (don't forget to re-export to HTML and add the assets folder to your project again). Currently, I run the slides in fullscreen on localhost and that seems to work fine for me.

Conclusion

In this post we learned how to export an Apple Keynote presentation to HTML. By doing so, we could add interactivity to our presentation so that our audience isn't just looking over our slides. We used emojis in this case, but the possibilities are really dependent on how creative you want to be.

Additionally, we saw how easy it is to add in AWS AppSync's subscriptions. Doing so allows us to only make use of the live interaction parts while not getting fully mixed in with the GraphQL side of things (though many apps will benefit from that 😉)

I hope you enjoyed this as much as I did putting it together!

Until next time, happy coding!

Fortunately for us, we laid a solid foundation for deploying our application when we first set it up in an earlier lesson. For the most part, this chapter can stand alone from the other chapters, though we'll use the project we've built so far so that we have something to deploy. However, if simply wanting to know how to deploy a CDK application, this guide is still for you.

In that previous post, we used a combination of thegit-branch library and the app.node.tryGetContext() method to dynamically create a stack that was dependent on the environment we were in.

Due to our diligence in the beginning, in this chapter, we'll see how easy it is to not only deploy our backend to AWS with GitHub actions but what a basic setup will look like when wanting to have a separate deployment flow for our develop and main branches.

Automation made simple with GitHub Actions

GitHub Actions is a powerful tool that allows you to automate workflows. With GitHub Actions, you can create custom workflows that automatically build, test and deploy your code whenever you push changes to your repository.

A GitHub action is defined in YML and is picked up by GitHub by being placed in a .github/workflows folder.

As seen in the image above, we'll take advantage of this by specifying a workflow with two different flows. In particular, depending on whether the event is a commit to our develop branch or a merge to our main branch, we'll do the following:

1. Checkout our application from GitHub

2. Perform the steps needed to build the application

3. Deploy the application

In your project, create the following directories and file: .github/workflows/aws.yml

In that file, paste the following.

🗒️ Because our deployment is dependent on the branch we are on, now is a good time to make sure we are on the develop branch and not the main branch. Also take a moment to push your project to GitHub so that the project is available.

A quick explainer of the lines is as follows:

1. lines 1-10: We give the action a name of our choosing, and define the criteria needed for our action to run

2. lines 13-15: Our workflow is called aws_cdk, if the event is a PR merge, or a push, then spin up an ubuntu server to run the following steps.

3. lines 17-22: The server is configured with git but that's it. So we create a step to checkout our repo and set up node version 18 using official GitHub-managed actions. Because NodeJS comes with NPM, we run npm install

4. lines 23-31: We need to install the CDK on our server. While this can be done manually, there is a popular and well-maintained 3rd-party action that does this. With it installed, we run the cdk diff command which is similar in spirit to git diff to view changes between what is local vs what is deployed. To do that, we provide AWS credentials as environment variables and our GitHub token environment variable for pull-request support.

5. lines 32-41: We deploy our application using the same GitHub action as the previous step except for this time we call the deploy command. Because we can't accept yes/no CLI prompts in this server, we pass a flag to auto-approve.

🗒️ If following along through the course, it's a good idea to run npx aws-cdk synth locally before deploying. This will compile your code to CloudFormation which serves as a good sanity check that there are no configuration errors.

GitHub action permissions are on a per-repo basis. Ensure your repo is configured correctly:

Lastly, recall our GitHub action uses environment variables to avoid us having to pass in our raw AWS credentials (which should never be done!).

The simplest way to get those is to grab them from your machine. When you set up your AWS account, those were stored in a ~/.aws directory. Grab those values and paste them into GitHub as shown in the following screenshot:

With our application configured, you can now deploy your code and view the action run from the Actions tab:

Deploy to Production

On every commit, we have our code deploying our develop environment, however, when a merge occurs on the main branch, we want to deploy our production environment.

To accomplish this, all we have to do is update our cdk.context.json file. Paste in the following:

{
    "globals": {
        "appName": "trip-logger",
        "region": "us-east-1",
        "appDescription": "A stack for a Travel pic viewer"
    },
    "environments": [
        {
            "environment": "develop",
            "branchName": "develop",
            "s3AllowedOrigins": ["*"]
        },
        {
            "environment": "production",
            "branchName": "main",
            "s3AllowedOrigins": ["*"]
        }
    ]
}

Commit your changes and wait for your develop branch to deploy. Once done, create a pull request to your main branch and merge it. You should see your production environment deploy 🎉

Conclusion

In this chapter, we saw how to deploy a CDK application to AWS using GitHub actions. While there are entire courses and varying opinions on how to manage your workflows and architecture, this method shows off the configuration options available while keeping the deployment straightforward.

While deploying our backend is useful on its own, in a fullstack application, you'll likely need the values from these services. In the next chapter, we'll see how this can be accomplished as we shift our focus to our frontend application.

Until then, happy coding!

🦦

At this point in the series, we should have a solid grasp on using various L2 constructs, passing arguments to them, and even a bit of knowledge with both setting permissions in policies and adding them to roles.

In this chapter, we'll expose ourselves to AppSync, both in terms of how it relates to GraphQL, but also as a service in the AWS ecosystem. By the end of this chapter, you'll have the tools in place to develop your next API with AppSync while understanding how it can best integrate as part of your backend architecture.

From the perspective of our Trip Logger application, this will complete the backend services in this stack!

AppSync is a powerful service, and if this is your first experience with it, be ready because it's going to change how you think about API development.

AWS AppSync

AppSync can be split up into two conceptual parts.

1. The GraphQL part: This includes features that are common to anyone building a GraphQL API

2. The fully-managed on AWS part: These are the parts that make it different from other GraphQL APIs.

Let's start by first talking about what GraphQL is and the benefits it gives to indie creators, and SaaS developers.

GraphQL in a Nutshell

While there are complete books, courses and such on GraphQL, I'll outline the 3 main parts to working with GraphQL on the backend:

GraphQL Schema

A schema is a contract for your API. It's made up of Queries, Mutations and Subscriptions. So instead of the traditional get,put,update and delete routes in REST, with GraphQL you use a Query to fetch data, a Mutation to update data (including deleting it), and a Subscription to listen for updates.

An example schema would look like the following:

🗒️ The general flow for defining an operation on a type is:

name(arguments): returnType

Also, note that as opposed to TypeScript, values are optional by default in GraphQL. To mark a value as non-null (aka required), add a !.

In terms of supported scalar types, GraphQL supports String, Int, Boolean , ID, and Float. In case you're wondering, ID is a string, but it's marking it as being unique.

Data Sources

The second concept of GraphQL is a data source. Nothing too fancy about this. A data source is simply where you are going to get your data from. This can be a database, a JSON file, a public API etc.

Resolvers

If a schema defines the data, and data sources are where the data lives, then a resolver sits in the middle and describes how to get that data. However, as opposed to a RESTful API, there aren't multiple routes to manage. GraphQL does this all through a single HTTP endpoint.

This is typically done in a GraphQL server. However, it can also be done in a Lambda function. The point here is that these are functions that are aware of the incoming request and can perform some logic based on the Query or Mutation operation.

As a frontend developer, this is similar in spirit to a reducer in libraries like Redux where there is a central hub that manages the state when actions are dispatched.

This is the appeal of GraphQL. When client applications ask for data, they don't need to know how the data is fetched, or where it comes from. Take the following schema for example.

When the frontend calls the getSocialRep query operation, they don't need to know that this is going to call the APIs for GitHub, Instagram, and Twitter. All they have to do is use a single endpoint to describe the data they need, and the resolvers connect to the various data sources to fulfill their request.

GraphQL on AWS

The problem with running GraphQL in a server is that you are paying for the server even when no one is using it and servers need to have their capacity scaled up and down manually based on usage.

To solve that, a lot of folks run GraphQL in a Lambda function. This solves both scaling and price. However, Lambda functions have their own limitations when it comes to cold starts, and need to manage memory capacity.

AWS AppSync is a fully-managed, fully-serverless solution for both scenarios. Because it's on AWS, it natively integrates with Cognito and DynamoDB. In addition, it automatically comes with subscription support by generating a WebSocket endpoint.

I've written and recorded a bunch of content on AppSync--even before joining the team, however, if wanting a quick start video on building a fullstack app with it, I created one that uses a great getting-started framework known as AWS Amplify.

With tens of thousands of customers, and billions of operations every single day, if you've ever had Taco Bell delivered to you, watched a show on HBO Max, saw stats on a live Ferrari F1 race, or purchased a ticket from Ticketmaster, then you've already interacted with AppSync.

How to Create an AppSync API in the CDK

Now that we talked about the pieces of a GraphQL API, let's put them to use.

Creating an AppSync schema

The schema serves as our contract so it's common to start here first.

To start, in lib/api/graphql create a file called schema.graphql and paste in the following:

# lib/api/graphql/schema.graphql
type Query {
    getTrip(id: ID!): Trip @aws_cognito_user_pools @aws_iam
    listTrips: [Trip]! @aws_cognito_user_pools @aws_iam
    getUser(id: ID!): User @aws_cognito_user_pools
}

type Mutation {
    createTrip(input: TripCreateInput!): Trip @aws_cognito_user_pools
    updateTrip(input: TripUpdateInput!): Trip @aws_cognito_user_pools
    deleteTrip(id: ID!): Trip @aws_cognito_user_pools
}

type Subscription {
    onTripCreate: Trip @aws_subscribe(mutations: ["createTrip"])
}

As mentioned earlier. We start things off by defining the operations we'd like to have.

However, there are three new things here: @aws_cognito_user_pools , @aws_iam , and @aws_subscribe .

These are known in GraphQL as directives and generally speaking, they are used to add special functionality to an operation. This is similar to higher-ordered functions in React.

In the case of these directives specifically, here is the breakdown of what each directive means in plain speak:

• @aws_cognito_user_pools: This operation can only be called if the person calling it is in a Cognito userpool (aka, if they're signed in).

• aws_iam: This operation can only be called if the person or AWS service, has a policy applied to their role that allows them to do so.

• @aws_subscribe: Listens for a change to the provided mutations and sends back the return type, Trip in this case, via a WebSocket when that happens.

You'll notice on the operations, the return type is often trip (or an array of trips with [trip]) and some operations take in an input. Let's define those as well.

Add the following to our schema:

type Trip @aws_cognito_user_pools @aws_iam {
    id: ID!
    createdAt: AWSDateTime!
    updatedAt: AWSDateTime!
    title: String!
    description: String!
    imgKey: String!
}

type User @aws_cognito_user_pools {
    id: ID!
    createdAt: AWSDateTime! # 2023-02-16T16:07:14.189Z
    updatedAt: AWSDateTime!
    username: String!
    email: AWSEmail!
}

# No "id" is required because we will create one automatically.
input TripCreateInput {
    title: String!
    description: String!
    imgKey: String!
}

input TripUpdateInput {
    id: ID!
    title: String!
    description: String!
    imgKey: String!
}

We again use directives on our Trip type to effectively say, "You have to be authenticated in a user pool or have a policy applied to receive this return type."

🗒️ AWSDateTime is a custom scalar offered by AppSync. It's a String type, but AppSync will automatically check to make sure it's a ISO formatted date (2023-02-16T16:07:14.189Z)

The full set of AppSync scalars can be found in the AppSync docs.

🗒️ Now is a good time to review our postConfirmation function. Notice how the data we store in the database overlap with what we have in for a User.

Creating an AppSync API

Now that we have an idea of what will be needed, let's call our yet-to-be-created AppSync API and give it the needed props.

In the lib/backend-trip-post-stack.ts file, paste in the following under our cognitoAuth function:

// import {createAppSyncTripAPI} from './api/appsync.ts'
const tripAPI = createAppSyncTripAPI(this, {
    appName: context.appName,
    env: context.environment,
    unauthenticatedRole: cognitoAuth.identityPool.unauthenticatedRole,
    userpool: cognitoAuth.userPool,
    travelDB,
    userDB,
})

As seen from the directives in our schema, access to our API can be provided via a user pool, or some policy on their role. To account for that, we are passing in our user pool, and our unauthenticatedRole from our Cognito identity pool.

Also, because we know our travelDB table and userDB table are what we will be performing operations against, we provided those as well.

🗒️ This again shows the power of the CDK.

Through the use of TypeScript, we simply pass constructs around just like in any other TypeScript application.

Initializing the L2 AppSync Construct

To use the AppSync L2 construct, create a file called /lib/api/appsync.ts and paste in the following:

import { envNameContext } from './../../cdk.context.d'
import { Construct } from 'constructs'
import * as awsAppsync from 'aws-cdk-lib/aws-appsync'
import * as path from 'path'
import { UserPool } from 'aws-cdk-lib/aws-cognito'
import { Table } from 'aws-cdk-lib/aws-dynamodb'
import { IRole } from 'aws-cdk-lib/aws-iam'

type AppSyncAPIProps = {
    appName: string
    env: envNameContext
    unauthenticatedRole: IRole
    userpool: UserPool
    travelDB: Table
    userDB: Table
}

export function createAppSyncTripAPI(scope: Construct, props: AppSyncAPIProps) {
    const api = new awsAppsync.GraphqlApi(scope, 'TripAPI', {
        name: `${props.appName}-${props.env}-TripAPI`,
        schema: awsAppsync.SchemaFile.fromAsset(
            path.join(__dirname, './graphql/schema.graphql')
        ),
        authorizationConfig: {
            defaultAuthorization: {
                authorizationType: awsAppsync.AuthorizationType.USER_POOL,
                userPoolConfig: {
                    userPool: props.userpool,
                },
            },
            additionalAuthorizationModes: [
                { authorizationType: awsAppsync.AuthorizationType.IAM },
            ],
        },
        logConfig: {
            fieldLogLevel: awsAppsync.FieldLogLevel.ALL,
        },
    })

    api.grantQuery(props.unauthenticatedRole, 'getTrip', 'listTrips')

    return api
}

Skipping past the imports and the types, we'll look at the main parts of the construct's config object:

1. schema: Here we load in the schema.graphql we created earlier.

2. authorizationConfig: This section configures the API's authorization settings. It specifies that the default authorization type is USER_POOL, meaning it uses AWS Cognito User Pools for authentication. Additionally, it accepts additional authorization modes. In our case, we're specifying IAM authorization type as an alternative mode, passing in the IAM role from our Cognito identity pool.

3. logConfig: This section enables logging for the API, with the field log level set to ALL. This means all resolvers' logs will be captured, including errors, information, and field-level data. When we start testing our API on the frontend, we'll see how to view these logs.

When we created our API we allowed users/services with the correct IAM permissions access. To update those roles so that they indeed have access to certain operations, we use the helper method grantQuery and pass in the role, and the queries we'd like that role to have access to.

With intellisense, it's possible to see the other operations as well:

Adding a Data Source to an AppSync API

We passed in our travelDB and userDB because that is where our Trip and User information is persisted. To add those as data sources to our API, add the following just before our return statement:

const TripDataSource = api.addDynamoDbDataSource(
  `${props.appName}-${props.env}-TripDataSource`,
  props.travelDB
)
const UserDataSource = api.addDynamoDbDataSource(
  `${props.appName}-${props.env}-UserDataSource`,
  props.userDB
)

It's worth taking some time to explore the other types of data sources that AppSync provides. This flexibility is part of the attraction to why AppSync is so widely recommended when building modern fullstack applications.

Creating AppSync Functions

Perhaps one of the most compelling reasons to use AppSync is how it handles resolvers.

In AppSync, your resolver logic is put into a pipeline. This pipeline consists of small operations (known as functions) that perform one piece of logic.

🗒️ We'll be talking about AppSync "functions" in this section quite a bit. It's important to know that these are not the same as Lambda functions.

Yes--these functions will be in JavaScript

Yes-- they will look like Lambda functions.

But they're not. In AppSync, a Lambda function is a data source, just like a DynamoDB table. An AppSync function is simply a step in a resolver, similar to promise-chaining with .then

If the idea of a pipeline resolver sounds fuzzy, check out this blog post I wrote that talks more about it.

To instill this concept, let's create our first AppSync function. Just under where we created our data source, add the following:

const createTripFunction = new awsAppsync.AppsyncFunction(
  scope,
  'createTripFunction',
  {
    name: 'createTripFunction',
    api,
    dataSource: TripDataSource,
    runtime: awsAppsync.FunctionRuntime.JS_1_0_0,
    code: awsAppsync.Code.fromAsset(
      path.join(__dirname, 'graphql/functions/Mutation.createTrip.js')
    ),
  }
)

Here we're creating an AppSync function that will be used for creating a Trip. This function is tied to the data source we created above. The function itself can be written in JavaScript or an older language known as VTL.

New applications shouldn't be using VTL and should opt for JavaScript, especially because the team will be releasing TypeScript support soon🤫

For a whirlwind tour of why this is a big deal, checkout the video below.

The code argument is where we'll write our AppSync logic.

Just to show how reproducible it is to create an AppSync function, let's create a function for getting Trip data from the table. Under our previous function, paste in the following:

const getTripFunction = new awsAppsync.AppsyncFunction(
  scope,
  'getTripFunction',
  {
    name: 'getTripFunction',
    api,
    dataSource: TripDataSource,
    runtime: awsAppsync.FunctionRuntime.JS_1_0_0,
    code: awsAppsync.Code.fromAsset(
      path.join(__dirname, 'graphql/functions/Query.getTrip.js')
    ),
  }
)

Feel free to create the code for thegetUserFunction, updateTripFunction, deleteTripFunction, and the listTripsFunction since they all follow the same format but have changed file paths and appropriate datasources.

Creating AppSync Pipeline Resolvers

As mentioned a couple of times now, a pipeline resolver is what gets triggered when a user makes a request to our API. So when we create our resolver, we have to tell what type and field to listen for.

To accomplish that, just beneath our AppSync functions, paste the following:

new awsAppsync.Resolver(scope, 'createTripPipelineResolver', {
  api,
  typeName: 'Mutation',
  fieldName: 'createTrip',
  code: awsAppsync.Code.fromAsset(
    path.join(__dirname, 'graphql/functions/passThrough.js')
  ),
  runtime: awsAppsync.FunctionRuntime.JS_1_0_0,
  pipelineConfig: [createTripFunction],
})

Recall a pipeline has a special before and after step. The before step allows us to perform logic (such as calculate values based on the arguments), while the after step allows us to perform additional formatting before returning the response to the user. We won't do either of those in this series, so I'm creating one JavaScript file that we'll reuse across all of our resolvers.

This pipeline resolver maps to our Mutation.createTrip operation and will call createTripFunction.

🗒️ In case you're wondering why the pipelineConfig accepts an array of functions, consider a scenario where we are creating an order from Stripe.

The first function would be to get the Stripe secret, if that was successful, then it would pass the secret to another function that would call the Stripe API.

Not only does this separate concerns, but it allows us to reuse the fetchStripeSecret function in other pipelines.

As before, once the steps are realized on how to create one resolver, creating another one becomes trivial. Let's create a resolver for the Query.getTrip operation by pasting in the following beneath the previous one:

new awsAppsync.Resolver(scope, 'getTripPipelineResolver', {
  api,
  typeName: 'Query',
  fieldName: 'getTrip',
  code: awsAppsync.Code.fromAsset(
    path.join(__dirname, 'graphql/functions/passThrough.js')
   ),
  runtime: awsAppsync.FunctionRuntime.JS_1_0_0,
  pipelineConfig: [getTripFunction],
})

Due to the steps being so similar, create the resolvers for the Query.getUser, Mutation.deleteTrip, Mutation.updateTrip, and the Query.listTrips operations. Make sure they each reference their respective pipelineConfig function.

🗒️ While it's important to remember we are defining our infrastructure, as opposed to creating an application, associating resolvers with functions can be a bit verbose.

For that reason, the AppSync team is looking into ways to condense the process of creating a resolver with only one function.

Defining AppSync Pipeline functions

In this and the next section, we're going to write the logic for all of our resolvers. This is one of the areas that sets AppSync apart from other GraphQL providers the most and why it's such a compelling reason to build a modern API with AppSync.

PassThrough Pipeline

Before talking about the functions, let's see an example.

In lib/api/graphql/functions create a file called passThrough.js and paste in the following:

// The before step.
// This runs before ALL the AppSync functions in this pipeline.
export function request(ctx) {
    console.log(ctx.args)
    ctx.stash.someValue = 42
    return {}
}

// The after step.
// This runs after ALL the AppSync functions in this pipeline.
export function response(ctx) {
    return ctx.prev.result
}

The above function is the before and after state in our pipeline. Notice how the request takes in an object that contains the context of the request. It also stores a value on the stash object called someValue. This allows functions further in pipeline to pull this value, without the value having to be passed down each through each function. Whatever the next function in line is, has to receive something. So we send an empty object.

The response also takes in its own context value and in this case returns the ctx.prev.result, which is whatever the previous function sent to it.

🗒️ What may clear things up is knowing that the request and response functions get transpiled by AppSync into VTL mapping templates. In VTL there is a request and response template.

This is why the request and response functions above can't be named anything else, and why they can't use features in JavaScript like fetch, or fs.

Going forward, I'll refer to the request and response functions as "mapping templates" or "templates" to make that point clear.

createTrip Function

link to docs

// lib/api/graphql/functions/Mutation.createTrip.js
import { util } from '@aws-appsync/utils'
export function request(ctx) {
    let id = util.autoId()
    let values = ctx.args.input

    return {
        operation: 'PutItem',
        key: util.dynamodb.toMapValues({ id }),
        attributeValues: util.dynamodb.toMapValues({
            __typename: 'Trip',
            createdAt: util.time.nowISO8601(),
            updatedAt: util.time.nowISO8601(),
            ...values,
        }),
    }
}
export function response(ctx) {
    return ctx.result
}

Based on our schema, we know the arguments that are optional and which ones are required. Since we know that, we use one of the built-in util methods to create a random id and capture the arguments that we were passed as input.

From there, we call the PutItem operation to create store an item in our table. AppSync knows which table we're working with because we assigned it as our data source.

🗒️ The @aws-appsync/utils library is preinstalled by the AppSync runtime so it's not necessary to install, however, it's nice to get the intellisense when developing.

To add the run library, run the following from the root of your project:

npm i @aws-appsync/utils

In the response template, we take the data that we receive from the DynamoDB (the newly created object in our Database, and forward it to our next step--the after step in our pipeline.

That's the complete flow of how data moves through our application.

For the next functions, I'll share a link to the docs, and point out any areas worth mentioning, but they will largely consist of the code for the mapping templates themselves.

deleteTrip Function

link to docs

// lib/api/graphql/functions/Mutation.deleteTrip.js
import { util } from '@aws-appsync/utils'

export function request(ctx) {
    return {
        operation: 'DeleteItem',
        key: util.dynamodb.toMapValues({ id: ctx.args.id }),
    }
}

export function response(ctx) {
    return ctx.result
}

updateTrip Function

link to docs

Note that both the updateTrip and createTrip both use the PutItem operation. The difference is that when creating a Trip there is no id to pass in since it's created automatically.

// lib/api/graphql/functions/Mutation.updateTrip.js
import { util } from '@aws-appsync/utils'
export function request(ctx) {
    let { id, ...values } = ctx.args.input

    return {
        operation: 'PutItem',
        key: util.dynamodb.toMapValues({ id }),
        attributeValues: util.dynamodb.toMapValues({
            __typename: 'Trip',
            updatedAt: util.time.nowISO8601(),
            ...values,
        }),
    }
}

export function response(ctx) {
    return ctx.result
}

getTrip Function

link to docs

// lib/api/graphql/functions/Query.getTrip.js
import { util } from '@aws-appsync/utils'

export function request(ctx) {
    return {
        operation: 'GetItem',
        key: util.dynamodb.toMapValues({ id: ctx.args.id }),
    }
}

export function response(ctx) {
    return ctx.result
}

listTrips Function

link to docs

While not shown in this example, with the scan operation it's possible to perform token-based pagination.

// lib/api/graphql/functions/Query.listTrips.js
export function request(ctx) {
    return  {
        operation: 'Scan',
    }
}

export function response(ctx) {
    const response = ctx.result.items

    return response
}

getUser Function

link to docs

// lib/api/graphql/functions/Query.getUser.js
import { util } from '@aws-appsync/utils'

export function request(ctx) {
    return {
        operation: 'GetItem',
        key: util.dynamodb.toMapValues({ id: ctx.args.id }),
    }
}

export function response(ctx) {
    return ctx.result
}

A Bit of Honesty

I'll be upfront because I know some of you like to poke around. Currently, each AppSync function does take a requestMappingTemplate and a responseMappingTemplate key. Further, the AppSync construct does have a MappingTemplate property that has full DynamoDB support for CRUD operations:

However, while those methods may be nice convenience APIs in the beginning. I wanted to show that writing JavaScript files, while verbose, is more valuable due to learning about how things are mapped under the hood.

🗒️ I would much rather have you refactor to something simpler and know how it works, than try to scale up and not understand it.

Conclusion

In this chapter, we dove deep into building out AppSync APIs. Not only did we cover schemas, directives, resolvers and data sources, but we also set up create, read, update, delete, and list functionality (with support for WebSockets) for an API in a ready-to-deploy, ready-to-modify way!

That's no small feat!

We also talked about AppSync functions and how they fit as pieces in a pipeline.

This was the last piece to this stack. In the next chapter, we'll talk all about deployment!

Until then, Happy Coding

🦦

However, it's also where I heard the horror stories of big bills due to random file uploads, assets being taken due to misconfigured permission and other aspects that scared me to be very happy to either pay for some 3rd-party service or settle with their limitations.

Reflecting on it now, it was never S3 keeping me away from using it, but my lack of knowledge about roles and policies in AWS, as well as CORS.

So in this post, not only will we see firsthand how simple creating an S3 bucket with a CDN is, but we'll discuss the security as well.

By the end of this chapter, I hope you'll be more confident and better prepared to work with permissions in your own applications by having a strong grasp on how they apply in our Trip Logger app.

Great Power

An Introduction to Amazon S3

As mentioned before, Amazon S3 is a storage service capable of storing practically any type of data. This could be PDF, CSV, images, JSON, or anything else.

🗒️ S3 is not a database

When you need to perform database operations like querying, sorting, and filtering data, it's not efficient to store that data in S3. S3 is designed to store and retrieve objects, like files, and accessing data in S3 requires downloading the entire object

In our Trip Logger application, we'll implement both reading and writing data into our S3 bucket. For reading, the viewer doesn't have to be logged in.

For writing into our bucket, the user will have to be authenticated.

Understanding S3 access levels

It's important to note, as seen in our architecture diagram below, that when it comes specifically to our S3 bucket, all requests are going through Cognito even if they aren't signed in. To understand this, we have to think about what it means to be unauthenticated.

When it comes to items stored in an S3 bucket, there are 3 essential states to consider:

1. Anonymous Access: Users who view our files on a different domain than our application.

2. Guest Access: Users who view our files on our domain, but have not authenticated.

3. Authenticated Access: Users who have signed into our application.

Using an e-commerce application as an example, guest access would be provided when a customer visits our site. They should have the ability to read public files without having to authenticate. However, the store owner may be able to log into the site and create, read, update, and delete products based on availability.

In addition, when a customer decides to purchase items, they may be taken away from our site, to a payment processor like Stripe. Stripe will need to read our product images from their domain instead of our own. This is an example of anonymous access.

With those concepts in place, let's create our first S3 bucket.

Creating a Simple S3 Bucket

Create a new file called lib/s3/tripPics.ts and paste in the following:

import { envNameContext } from './../../cdk.context.d'
import { Construct } from 'constructs'
import * as s3 from 'aws-cdk-lib/aws-s3'

type CreateTripPicsBucketProps = {
    appName: string
    env: envNameContext
}

export function createTripPicsBucket(
    scope: Construct,
    props: CreateTripPicsBucketProps
) {
    const fileStorageBucket = new s3.Bucket(
        scope,
        `${props.appName}-${props.env}-bucket`,
        {}
    )

    return fileStorageBucket
}

Skipping over the concepts we've already gone over, you'll see that the L2 construct for creating an S3 bucket simply takes in scope, an ID as the required props. When it comes to the configuration object, it doesn't require any so it's an empty object.

🗒️ Worth noting is there is a bucketName field that we can pass in. However, it is best practice to let CloudFormation (via the CDK) generate this name for you.

This is due to S3 bucket names needing to be globally unique.

In our lib/backend-trip-post-stack.ts file, call out createTripPicsBucket function by pasting in the following underneath our database references:

const tripPicsBucket = createTripPicsBucket(this, {
    appName: context.appName,
    env: context.environment,
})

That's it! You've now created an S3 bucket. While this is great, for us to make any use of it in our application, we'll have to apply some permissions to it.

Great Responsibility

S3 Bucket Permissions

"With great power, comes great responsibility."

- Uncle Ben🕷️

So far in our Trip Logger application, we had a brief exposure to policies when we gave our Lambda function permission to write data to our User table. However, for our bucket, it's important to understand the permissions we're setting and not rely on those methods.

To accomplish that, let's first talk about a friend we all know and love:

CORS

Cross-origin-resource-sharing (CORS) is the bane of many frontend developers.

By default, a server can talk to another server. However, a browser can only talk to a server if that server has allowed specific methods and headers saying it's ok to do so.

As frontend developers, we know this--and yet, I still run into this issue to this day.

With regards to our S3 bucket, it lives on an AWS server somewhere. We would like to read, update, and delete images from that bucket from our browser. To do that, we have to enable CORS on our bucket.

Fortunately, our empty config object on our bucket has a cors property that we can add. Back in our lib/s3/tripPics.ts file, paste in the following:

export function createTripPicsBucket(
    scope: Construct,
    props: CreateTripPicsBucketProps
) {
    const fileStorageBucket = new s3.Bucket(
        scope,
        `${props.appName}-${props.env}-bucket`,
        {
            // the new part
            cors: [
                {
                    allowedMethods: [
                        s3.HttpMethods.GET,
                        s3.HttpMethods.POST,
                        s3.HttpMethods.PUT,
                        s3.HttpMethods.DELETE,
                    ],
                    allowedOrigins: props.allowedOrigins,
                    allowedHeaders: ['*'],
                    exposedHeaders: [
                        'x-amz-server-side-encryption',
                        'x-amz-request-id',
                        'x-amz-id-2',
                        'ETag',
                    ],
                },
            ],
        }
    )

    return fileStorageBucket
}

• allowedMethods: A list of predefined HTTP methods. It's important to note, this is just saying what's possible to do from the browser. The actual user authorization permission will be handled later.

• allowedOrigins: An array of domains that can perform the above allowedmethods.

• allowedHeaders: An array containing headers that the frontend can pass to the S3. By specifying *, we are allowing all headers to be passed.

• exposedHeaders: The headers S3 sends to the client.

While not important to understand, simply for those curious, here's a bit on what the exposed header values relate to:

• x-amz-server-side-encryption: Whether the object in S3 is stored using server-side encryption, and if so, which encryption algorithm was used

• x-amz-request-id: A unique identifier for the request made to S3, which can be used for troubleshooting purposes

• x-amz-id-2: A string that identifies the Amazon S3 bucket that processed the request

• ETag: A unique identifier for the version of the object stored in S3, which can be used for caching purposes and to determine if the object has been modified

🗒️ I'll admit, I cheated a bit here. I know that we'll be using the AWS Amplify JS libraries for S3 image handling on our frontend, and they have a section dedicated to supplying the CORS configuration.

The allowedOrigins field is handled by props because the origin will change depending on if we are on our develop environment, or production.

To include that field in our props, ensure the cdk.context.d.ts file has:

s3AllowedOrigins: [string]

Likewise, in the environments array, add the following to the object:

"s3AllowedOrigins": ["http://localhost:3000"],

By now, TypeScript should be complaining in our stack that the props are missing. Update the relevant files to contain the needed props and values.

Understanding Roles and Policies

A crucial part of working with AWS is understanding roles and permissions. These are managed in an AWS service called IAM, as such, you'll often hear "IAM Role" or "IAM Policy".

While this is worthy of its own series, the simple explanation is this:

A policy in AWS is a rule that says who can do what. "Who" in this context can be an AWS user or another AWS service.

A role is a set of policies that describe who the user will become if that role is applied to them.

A common metaphor is that a role is a hat. If you put on a construction hat, you inherit all of the authority of a construction worker. If you take the hat off and put on a captain's hat, you now have full authority to perform all the duties of a captain.

🗒️ The subtle, but important, concept here is that only one hat can be put on at a time. 🎩👒⛑️

Granting Access to our S3 Bucket Through IAM Policies

The first policy we'll create is a common one: allowing read access to our bucket.

In our lib/s3/tripPics.ts file, past the following before the return statement:

const allowReadFromBucket = new iam.PolicyStatement({
    effect: iam.Effect.ALLOW,
    principals: [new StarPrincipal()],
    actions: ['s3:GetObject'],
    resources: [`${fileStorageBucket.bucketArn}/public/*`],
})

At the top of the file, also include the following imports:

import * as iam from 'aws-cdk-lib/aws-iam'
import { StarPrincipal } from 'aws-cdk-lib/aws-iam'

As you can see there is an L2 construct for easily creating IAM policies. The StarPrincipal used to say "anyone" in an policy.

In plain speak, this policy reads as, "Allow anyone to get an object from an S3 bucket--specifically, any object from the public folder of the fileStorageBucket."

🗒️ I purposely put the policy keys in this order so that it read like that. Because it's just a JavaScript object, the order doesn't actually matter, but I find it helps when first learning.

Worth talking about is the fileStorageBucket.bucketArn line. Every AWS service has a unique identifier known as an Amazon Resource Name (ARN). In our case, we appended the /public/* part to further scope down access to a folder and not the entire bucket.

Now that we have the policy to read from our bucket, let's add another for signed-in users:

// Let signed in users CRUD on a bucket
const canReadUpdateDeleteFromPublicDirectory = new iam.PolicyStatement({
    effect: iam.Effect.ALLOW,
    actions: ['s3:PutObject', 's3:GetObject', 's3:DeleteObject'],
    resources: [`${fileStorageBucket.bucketArn}/public/*`],
})

As you can see, it's similar to the first one, but has more permission allowed. Additionally, we removed the IAM principal since in the next section we'll promote this policy to a "managed policy".

Adding IAM Policies to IAM Roles

Think back, or look up, at our architecture diagram. Then try to answer the following question: We are creating policies that allow access to our S3 bucket, but for who?

Remember when I said the "who" can be a user or an AWS service?

We are providing access to our Amazon Cognito identity pool.

Just under our previous policy, paste in the following:

new iam.ManagedPolicy(
    scope,
    'SignedInUserManagedPolicy',
    {
        description:
            'Allow access to s3 bucket by signed in users.',
        statements: [canReadUpdateDeleteFromPublicDirectory],
        roles: [props.authenticatedRole],
    }
)

AWS comes with a set of policies. When you first created your first AWS user, you likely used one: AWSAdminstratorFullAccess

The distinction is small, but what's important to note is that most AWS services will let you give them a regular policy as we defined earlier, but some require an AWS-managed policy and this is how we create one. Not only does it accept an array of policies, but it also accepts an array of roles for us to apply.

In our case, this role is the authenticated state of our Cognito identity pool. That's to say when a user makes a request, for one of our services, as part of the request, they will pass information about their current auth state (via a header). If they are authenticated, then this role will be invoked.

To pass the role from our identity pool, first, update the CreateTripPicsBucketProps in this file so it's expected:

type CreateTripPicsBucketProps = {
    appName: string
    env: envNameContext
    allowedOrigins: [string]
    authenticatedRole: iam.IRole
}

Next, in our lib/backend-trip-post.stack.ts file, simply pass the role from the identity pool to the bucket as such:

const tripPicsBucket = createTripPicsBucket(this, {
    appName: context.appName,
    env: context.environment,
    allowedOrigins: context.s3AllowedOrigins,
    authenticatedRole: cognitoAuth.identityPool.authenticatedRole,
})

Hopefully, it's starting to make sense at this point that much like frontend applications, the right level of abstraction and file organization can greatly pay off when it comes to passing values around!

Improving Content Delivery with Amazon CloudFront

You may be wondering why we didn't also create a managed policy for the unauthenticated role provided by our Cognito identity pool.

The reason is that we're not going to allow direct access to our S3 bucket at all.

The first policy we created was simply to get us comfortable working with policies. We won't actually be using it and instead will have our users access images from a content delivery network (CDN).

Getting started with a Content Delivery Network (CDN)

When we request a file from S3, that image has to be retrieved from an AWS server and is then loaded into our browser. Now, browsers may opt to do some caching, but it's only for your personal benefit. If your neighbor wants to see that same image, they would have to make that full network trip as well, even though you already brought the image next door.

A CDN solves that by caching the image at the nearest AWS network location near you. Now, when your neighbor requests that image you've cached it closer to you, so they get a faster response time.

An added benefit is that we don't need to allow public read access to our bucket since our CDN will be sitting between our bucket and our users.

To create our CDN, in the lib/s3/tripPics.ts file, add the following imports:

import * as awsCloudfront from 'aws-cdk-lib/aws-cloudfront'
import { S3Origin } from 'aws-cdk-lib/aws-cloudfront-origins'

Next, replace the IAM policy that just allowed Get:Object access with the following:

const fileStorageBucketCFDistribution = new awsCloudfront.Distribution(
    scope,
    `${props.appName}-${props.env}-CDN`,
    {
        defaultBehavior: {
            origin: new S3Origin(fileStorageBucket, { originPath: '/public' }),
            cachePolicy: awsCloudfront.CachePolicy.CACHING_OPTIMIZED,
            allowedMethods: awsCloudfront.AllowedMethods.ALLOW_GET_HEAD,
            cachedMethods: awsCloudfront.AllowedMethods.ALLOW_GET_HEAD,
            viewerProtocolPolicy:
                awsCloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
        },
    }
)

In addition to setting caching methods and redirecting HTTPS, the important part here is:

1. The L2 CloudFront construct makes this really simple

2. The line origin: new S3Origin(fileStorageBucket, { originPath: '/public' })

When our CloudFront distribution deploys, it'll generate a URL for us. This will directly map to our S3 bucket. However, we only want to map to the /public folder.

By setting the originPath, a request to my-cdn.com/image.jpg will now forward to our S3 bucket: my-s3-bucket/public/image.jpg.

Lastly, because we are introducing two new services that will be used by our frontend, let's make sure to return them both.

Update the return statement to the following:

return { fileStorageBucket, fileStorageBucketCFDistribution }

🗒️ A note on pricing

For S3 pricing, after the 1-year free tier period, the cost of storing your first 50 terabytes of data in the us-east-1 region is $0.023 per GB. There are also data retrieval costs at $0.0004/1000 GET requests and $0.005/1000 PUT or DELETE requests.

For Amazon CloudFront pricing, their always-free tier includes the following:

• 1 TB of data transfer out per month

• 10,000,000 HTTP or HTTPS Requests per month

• 2,000,000 CloudFront Function invocations per month

• Free SSL certificates

• No limitations, all features available

Conclusion

In this post, we created an Amazon S3 bucket and an Amazon CloudFront distribution. My hope is what came across in this chapter is that creating an S3 bucket and a CDN took a relatively small amount of code and that the real focus was understanding policies and roles.

IAM configurations take time and practice. Fortunately, we'll continue to touch on them throughout this series. However, with what we created today, you now have the tools to create your own buckets with many best practices in mind.

In the next chapter, we'll bring our backend services together by creating a modern, full-managed, API that is not only completely serverless, but also completely functionless.

Until then, happy coding!

🦦

Your customers don't care that you have a fancy homegrown solution for hashing and salting passwords. They just want a safe and secure way to log into your app. Not only is signing up for a service common but the complete handling of the user flow is also expected.

So far, in our application, we have two DynamoDB tables and a Lambda function. These are both examples of services that do one thing really well. However, some services offer multiple services under their name. Amazon Cognito is such a service.

Cognito is comprised of three main services: a user pool, identity pool, and a user pool client.

Let's discuss each of those to see what they provide.

Authentication

Frontend developers use authentication to provide credentials that identify who they are. This is often done by providing an email and password, or by signing in with a social provider. Popular solutions like Auth0 and Auth.js are commonly used in the frontend/indie hacker community for their ease of use and developer experience.

When working with AWS services, the preferred solution is a Cognito userpool. This service is a directory or pool of users that contains information about the users in your application. It offers a complete sign-up experience, including sign up, sign in, sign out, password recovery, and more. It also allows for simple integration with Google and Facebook log-ins. The Amplify JavaScript libraries further simplify the authentication experience.

When a user signs up for an application using Cognito, a unique ID is generated for them, along with their email and username. While custom attributes can be added, they are generally expected to remain unchanged. This is because that information is stored in the JSON Web Token (JWT) provided by Cognito. To avoid users having to log out and log in to update their information, it's best to store user data in a User table.

🗒️ The combination of Cognito -> Lambda -> DynamoDB is a common approach in both the serverless community and the SaaS community due to its flexibility, scalability, and robustness.

Creating a Cognito Userpool with the AWS CDK

In our Trip Logger CDK project, create a following in the lib/cognito/auth.ts.

import { Construct } from 'constructs'
import * as awsCognito from 'aws-cdk-lib/aws-cognito'
import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs'
import { envNameContext } from '../../cdk.context'

type CreateTravelUserpool = {
    appName: string
    env: envNameContext
    addUserPostConfirmation: NodejsFunction
}
export function createTravelUserpool(
    scope: Construct,
    props: CreateTravelUserpool
) {
// the L2 Construct for a userpool
const userPool = new awsCognito.UserPool(scope, `${props.appName}-${props.env}-userpool`, {
  userPoolName: `${props.appName}-${props.env}-userpool`,
  selfSignUpEnabled: true,
  accountRecovery: awsCognito.AccountRecovery.EMAIL_ONLY,
  userVerification: {
    emailStyle: awsCognito.VerificationEmailStyle.CODE,
  },
  standardAttributes: {
    email: {
      required: true,
      mutable: true,
    },
  },
})
    return { userPool }
}

At this point in the series, I'll skip over the types and the function and instead focus on the L2 Cognito construct itself. From there we can discuss the following properties of our userpool:

• userPoolName: The name of the user pool. This is a required field.

• selfSignUpEnabled: A boolean value that indicates whether users can sign themselves up for the user pool.

• lambdaTriggers: An object that allows us to hook into various lifecycles of a user authentication process and invoke a lambda function in response.

• postConfirmation: A lifecycle event that is triggered after a user confirms their account registration.

• accountRecovery: Determines the account recovery method. In this case, EMAIL_ONLY is specified, which means that users can recover their accounts using only their email addresses.

• userVerification: An object that specifies the type of user verification. In this case, emailStyle is set to awsCognito.VerificationEmailStyle.CODE, which means that verification codes will be sent to users via email.

• standardAttributes: An object that specifies the standard attributes for the user pool. In this case, only the email attribute is set with required and mutable properties.

• required: When set to true, then the email attribute is required, and users must provide a value for this attribute during sign-up.

• mutable: Determines whether the email attribute can be updated by the user.

Creating a Cognito Web Client with the AWS CDK

Our userpool is just that--a place where we store users. Cognito doesn't know (or care) how our users get there and we have to tell it. To do that, we use the L2 Cognito UserPoolClient to create a web client and pass it to our userpool.

Replace the return {userpool} code above with the following:

const userPoolClient = new awsCognito.UserPoolClient(
    scope,
    `${props.appName}-${props.env}-userpoolClient`,
    { userPool }
)
return {userpool, userPoolClient}

Authorization

If authentication is a bouncer at a nightclub that checks your ID before getting in, then authorization is the V.I.P. access lounge that only certain people can get into.

That's to say, authentication is who you are, while authorization is what you are allowed to do.

Amazon Cognito handles authorization via identity pools.

When it comes to authorization, we're not just talking about the users that have authenticated with our application. This also applies to how unauthenticated users interact with our app, and by extension, AWS services.

This will make more sense in the next section where we add image support to our application with AWS S3.

Creating a Cognito Identity Pool with the AWS CDK

For a service feature so powerful, actually creating an identity pool is a bit lackluster.

For the last time, replace the return statement in our function with the following:

const identityPool = new IdentityPool(
  scope,
  `${props.appName}-${props.env}-identityPool`,
  {
    identityPoolName: `${props.appName}-${props.env}IdentityPool`,
    allowUnauthenticatedIdentities: true,
    authenticationProviders: {
      userPools: [
        new UserPoolAuthenticationProvider({
          userPool: userPool,
          userPoolClient: userPoolClient,
        }),
      ],
    },
  }
)

Aside from giving it a name, and passing in our userpool and client, the only thing to call out is that we explicitly tell our identity pool to allow unauthenticated users to access our AWS services. What those users can do is still fully up to us, but the ability to even attempt access is now provided.

However, you should notice at this point that TypeScript is unhappy. Specifically, it can't find the IdentityPool and UserPoolAuthenticationProvider constructs.

This is because these L2 constructs are currently in alpha and haven't been merged into the main library yet.

🗒️ As a word of caution, be careful when using alpha constructs as they can have breaking changes. I'm opting to use them in this series because well...I work at AWS and may or may not have knowledge that these specific features are fine to use for our purposes.

To install the alpha package, run the following command:

npm i @aws-cdk/aws-cognito-identitypool-alpha

Updating our stack with Cognito

As was the same in previous chapters, we'll invoke our createTravelUserpool function by passing in the appName , envand the addUserPostConfirmation props. This should be done just beneath the Lambda function we created in the previous chapter, but before our database (no reason in particular, I just like to keep related services together).

// created in previous chapter
const addUserFunc = new NodejsFunction(this, 'addUserFunc', {
    functionName: `${context.appName}-${context.environment}-addUserFunc`,
    runtime: Runtime.NODEJS_16_X,
    handler: 'handler',
    entry: path.join(__dirname, `./functions/addUser/main.ts`)
})

// import this function and call it with the appropriate props
const cognitoAuth = createTravelUserpool(this, {
    appName: context.appName,
    env: context.environment,
    addUserPostConfirmation: addUserFunc,
})

// ...databases we created in the previous chapter

🗒️ A note on pricing:

Amazon Cognito has one of the most generous pricing tiers of any fully managed auth provider. Every account is allowed 50,000 monthly active users as part of the free tier and this extends past the first 12 months of an account being created.

Beyond that, each user has a cost of $0.05. While this may seem pricy, my take is that if you have over 50k MAU's signed up using your app and you haven't figured out a way to monetize that, come see me. We have bigger things to talk about 😜

Conclusion

In this post, we talked about authentication and authorization as they relate to both Amazon Cognito, and our Trip Logger application. Additionally, we added our Lambda function as a postConfirmation trigger. This enables us to display profile information to our users in a way where it can be updated without them having to log in and out.

Due to Cognito being made up of child services, it's hard to explain how little fun it is to perform what we accomplished by clicking through the AWS console. Even today, it would trip me up. This is truly one of the best areas to showcase the power of the AWS CDK and infrastructure-as-code in general.

In the next post, we'll talk about asset storage with one of the very first services that AWS came out with Amazon S3.

Until then, happy Coding!

🦦

Recall from our architecture diagram that we have two tables:

• TravelPost: This will contain information about the trip that was taken. For our application, full CRUD operations will be handled by our API.

• User: This will contain information about the signed-in user.

In addition, we have a serverless function that will populate the User table once a user successfully signs up for the first time.

In the next chapter, we'll complete this flow by setting up authentication.

Going NoSQL with DynamoDB

DynamoDB is a NoSQL database service provided by AWS. Unlike traditional SQL databases that store data in tables with fixed columns and relationships between them, DynamoDB stores data as JSON objects and doesn't rely on strict relationships between tables

From a frontend perspective, DynamoDB can be used to store and retrieve data for web or mobile applications. Moreso, it can help you store and retrieve data for your applications with low latency and high performance, and allows for flexible and scalable data models that can adapt to changing needs.

Creating the Travel Table

To get started creating our first table, update our backend-trip-post-stack.ts file to look like the following:

import { CDKContext } from './../cdk.context.d'
import * as cdk from 'aws-cdk-lib'
import { Construct } from 'constructs'
// 👇 this is new
import {createTravelTable} from './database/tables'

export class BackendTripPostStack extends cdk.Stack {
    constructor(
        scope: Construct,
        id: string,
        props: cdk.StackProps,
        context: CDKContext
    ) {
        super(scope, id, props)
        // 👇 this is new
        const travelDB = createTravelTable(this, {
            appName: context.appName,
            env: context.environment,
        })
    }
}

Note that in addition to the import statement, we are calling a function called createTravelTable. The function takes in two arguments:

• this: This represents the current stack we are in.

• props : An object that represents values we'd like to pass. In our case, we passing the application name from our cdk.context.jsonfile, as well as the current environment.

🗒️ I personally, like to keep my stack files to where I'm just passing values to services and the actual creation of those services happens in the related file.

This is a design choice and not a set convention.

With the function in place, let's define our first construct.

From the lib directory, create /database/tables.ts file and paste in the following:

import { Construct } from 'constructs'
import * as awsDynamodb from 'aws-cdk-lib/aws-dynamodb'
import { RemovalPolicy } from 'aws-cdk-lib'
import { envNameContext } from '../../cdk.context'

type BaseTableProps = {
    appName: string
    env: envNameContext
}
type createTravelTableProps = BaseTableProps & {}

export function createTravelTable(
    scope: Construct,
    props: createTravelTableProps
): awsDynamodb.Table {
    const travelTable = new awsDynamodb.Table(scope, 'TravelTable', {
        tableName: `${props.appName}-${props.env}-TravelTable`,
        removalPolicy:
            props.env === 'develop' ? RemovalPolicy.DESTROY : RemovalPolicy.RETAIN,
        billingMode: awsDynamodb.BillingMode.PAY_PER_REQUEST,
        partitionKey: { name: 'id', type: awsDynamodb.AttributeType.STRING },
    })

    return travelTable
}

🗒️ Since this is our first construct, we'll spend some time going over the arguments and props in a bit more detail. Over time, we'll just focus on the meaningful parts.

The first import is the Construct. The Construct class is a base class for all constructs in AWS CDK, including the cdk.Stack class. By using the Construct type for the scope parameter, we ensure that the function can accept any construct, not just a cdk.Stack instance.

Next, we import awsDynamodb. This is the L2 construct from the CDK library. Note the import path of aws-cdk-lib/aws-dynamodb. All official L2 constructs are bundled under aws-cdk-lib.

For the props, we already know we'll have another table, so we're creating a BaseTableProps type that both will share, while still allowing each table to define its own.

As far as invoking the actual construct itself, we wrapped it in a function so we could pass in our appName and environment arguments.

All constructs are created with the new command and typically expect a format of new Construct(scope, id, config). In the case of this table, it has the following:

• scope: A reference to the current stack or construct.

• id: A unique identifier for the table.

• config: An object that configures the properties of the table, including:

  • tableName: The name of the table. We combine our id with our props.

  • removalPolicy: A RemovalPolicy determines whether the table is deleted or retained when the stack is deleted. In develop we set it to destroy the table if we destroy our stack. For other branches, it'll remove it from the stack, but keep the table itself.

  • billingMode: The billing mode for the table. While we can specify the read capacity to optimize our billing and throughput, most applications will benefit from the PAY_PER_REQUEST model that will scale up and down automatically based on our needs.

  • partitionKey: The partition key for the table specifies how data is partitioned and stored in the table. In this case, the partition key is a string id. This serves as a unique identifier for all of the items in our database.

🗒️ A note on pricing:

Pricing for AWS services can be confusing and I'll do my best to call them out as we go along. Some services have a free tier during the first year of an AWS account opening. Others have it forever.

DynamoDB offers a generous free tier of 25GB of storage and 100GB of data transfer per month. This is per account, but means for our application, not only are there no servers to manage but there is also no cost.

Creating the User Table

As for the parts we've already familiar with, let's add those in.

While still in the lib/backend-trip-post-stack.ts file, import a createUserTable function and add the following underneath our travelDB function:

//...rest of imports
import { createTravelTable, createUserTable } from './databases/tables'

//...rest of code
//userDB
const userDB = createUserTable(this, {
    appName: context.appName,
    env: context.environment,
    addUserFunc,
})

Here we're calling a createUserTable function and in addition to our context props, we're also passing in the function we just created.

In the lib/databases/tables.ts file, we'll create the createUserTable which will look similar to what we created earlier. To do so, paste in the following:

type CreateUserTableProps = BaseTableProps & {}
export function createUserTable(
    scope: Construct,
    props: CreateUserTableProps
): awsDynamodb.Table {
    const userTable = new awsDynamodb.Table(scope, 'UserTable', {
        tableName: `${props.appName}-${props.env}-UserTable`,
        removalPolicy:
            props.env === 'develop' ? RemovalPolicy.DESTROY : RemovalPolicy.RETAIN,
        billingMode: awsDynamodb.BillingMode.PAY_PER_REQUEST,
        partitionKey: { name: 'id', type: awsDynamodb.AttributeType.STRING },
    })

    return userTable
}

Creating our Lambda Function

What is a Lambda function

Our User table will be populated by a Lambda function. A Lambda function is often referred to as a "serverless function" when not referring to just AWS, I'll say Lambda function throughout this series, but just to get us on the same page, for this section I'll say serverless function.

As a frontend/fullstack developer, you may have an idea of what a serverless function is--and for the most part, you're probably correct, but there are some important pieces I want to make sure we understand, specifically the following:

1. A serverless function executes a bit of code, and then it stops. As opposed to a server (which can be eternally running), a serverless function is ephemeral. It spins up its own environment and when it's done executing and requests have stopped coming in, it'll eventually delete itself.

2. A serverless function takes in an event argument. This is contextual. Just like in JavaScript anything can call a function, the same is true for a serverless function. Because of that, the event object that every function receives will vary based on what is invoking it.

3. A serverless function is not an API route but a component of one. An API route is made up of a gateway (the thing that receives the HTTP request), and the function to invoke (the serverless function). This is important because we often think functions can only be invoked as part of a network request, but again, it can be from just about anything.

To emphasize that last point about anything being able to call a Lambda function, our function will be triggered every time a user signs up for our application.

Defining the Lambda function

A Lambda function definition is referred to as its handler.

To define a handler for our Lambda function, create a new file called lib/functions/addUserPostConfirmation/main.ts and paste in the following:

import * as AWS from 'aws-sdk'
const docClient = new AWS.DynamoDB.DocumentClient()
//typeScript types so that our "event" object is defined
import { PostConfirmationConfirmSignUpTriggerEvent } from 'aws-lambda'

exports.handler = async (event: PostConfirmationConfirmSignUpTriggerEvent) => {
    const date = new Date()
    const isoDate = date.toISOString()

    //construct the param
    const params = {
        TableName: process.env.USER_TABLE_NAME as string,
        Item: {
            __typename: 'User',
            id: event.request.userAttributes.sub,
            createdAt: isoDate, // ex) 2023-02-16T16:07:14.189Z
            updatedAt: isoDate,
            username: event.userName,
            email: event.request.userAttributes.email,
        },
    }

    //try to add to the DB, otherwise throw an error
    try {
        await docClient.put(params).promise()
        return event
    } catch (err) {
        console.log(err)
        return event
    }

The AWS SDK gives us a utility for adding data to a table via JSON with a DocumentClient. From there, we construct or params. These exact reason for adding these items will be revealed in out API chapter, but for now, it's enough to know this object is what is going to be added to our database.

You should be getting TypeScript errors relating to the aws-sdk and the aws-lambda packages. To fix those, it's important to know two things:

1. The AWS SDK is automatically installed in Lambda functions running in AWS. This means when we install it, we only have to install it as a dev dependency.

2. Recall Lambda functions are ephemeral and have their own environment. So when we install dependencies for them, they live in their own package.json file.

From your terminal, change into the lib/functions/addUserPostConfirmation directory and run the following commands and the errors should disappear:

npm init -y && npm i -D aws-sdk @types/aws-lambda

While the function itself will be used by our authentication service, we can create the function by calling the NodejsFunction L2 construct.

In the same the addUserPostConfirmation directory, create a file called construct.ts and paste in the following:

import { Table } from 'aws-cdk-lib/aws-dynamodb'
import { Runtime } from 'aws-cdk-lib/aws-lambda'
import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs'
import { Construct } from 'constructs'
import * as iam from 'aws-cdk-lib/aws-iam'
import path = require('path')
import { envNameContext } from '../../../cdk.context'

type CreateAddUserPostConfirmationProps = {
    appName: string
    env: envNameContext
    userTable: Table // 👈 Our function expects a DynamoDB table
}

export const createAddUserPostConfirmation = (
    scope: Construct,
    props: CreateAddUserPostConfirmationProps
) => {
    const addUserFunc = new NodejsFunction(scope, 'addUserFunc', {
        functionName: `${props.appName}-${props.env}-addUserFunc`,
        runtime: Runtime.NODEJS_16_X,
        handler: 'handler',
        entry: path.join(__dirname, `./main.ts`),
        environment: {
// pass the DynamoDB table name to the function as an env var
            USER_TABLE_NAME: props.userTable.tableName,
        },
    })

// Give our function permission to add an item to DynamoDB
    addUserFunc.addToRolePolicy(
        new iam.PolicyStatement({
            effect: iam.Effect.ALLOW,
            actions: ['dynamodb:PutItem'],
            resources: [props.userTable.tableArn],
        })
    )
    return addUserFunc
}

When using L2 constructs, they all follow a similar pattern. So even though this is a completely different AWS service, it can be distilled down to the same signature as our previous DynamoDB tables:

new ConstructName(scope, id, configObject)

In AWS, services are deny-by-default. This means unless permissions are defined (either explicitly or implicitly), then they can't talk to one another.

In the next chapter, we'll dive deeper into this concept and create our own access policies when we talk about S3.

It's worth noting that constructing a Lambda function with the CDK comes in two flavors:

1. A generic construct that allows for code to be written in many different languages

2. ANodejsFunction construct that only works with JavaScript and TypeScript files, but handles the bundling and transpiling with esbuild for us.

   Since we wrote our function in TypeScript, let's install esbuild as a dev dependency so that the CDK can automatically handle the transpilation process for us.

In the root of our project, run the following command:

npm i -D esbuild

We defined our function handler, and create the construct. All that's left to do is add the function to our stack.

Back in our lib/backend-trip-post-stack.ts file, paste in the following:

const addUserFunc = createAddUserPostConfirmation(this, {
    appName: context.appName,
    env: context.environment,
    userTable: userDB
})

Congratulations! You've just learned how to create 2 databases and a Lambda function in the CDK. Furthermore, our Lambda function has environment variables and permission to talk to a database.

🗒️ A note on pricing:

Per the AWS pricing page for Lambda, "The AWS Lambda free tier includes one million free requests per month and 400,000 GB-seconds of compute time per month"

While the pricing can be a bit confusing due to it being based on both requests and processing time, the gist is that this is a free service for our needs and it cost fractions of a penny for many applications.

Feel free to checkout the pricing examples in the docs to get a more concrete example.

Conclusion

With that in place, we have now successfully provisioned two DynamoDB tables and a Lambda function 🎉

In this section, we dove deep into how CDK constructs are initialized, the arguments they receive and how to add TypeScript types to them. We also discussed what a Lambda function is, and how to create one in TypeScript.

Hopefully, at this point, you're starting to see that creating AWS services in code is part understanding concepts and part calling methods available on L2 constructs. Once those are in place, it's a matter of figuring out how best to organize your code.

In the next chapter, we'll talk all about authentication and authorization with Amazon Cognito.

Until then, happy coding!

🦦

In tech, solutions are often ended with "...but it depends". Few things are absolute. However, there is something everyone can agree on: It's best to learn by doing.

So when I set out to create a guide for frontend developers working with the AWS CDK, I didn't want to tell concepts (and if you've been following my blog for a while, you know that's not my style). I wanted to deliver a guided path towards building a fullstack, fully-typed, fully serverless project so that frontend developers can automate their backend infrastructure.

I keep saying this is meant for "frontend" developers, but when it comes to modern frontend development, that definition is pretty loose. As mentioned in the initial chapter of this series, there is a specific demographic that I'm targeting.

Prereqs

While it's possible to read certain chapters in this series to pick up a particular solution, it's meant to be followed in sequence. At this point, you should have an idea of whether this guide is for you and also have a local environment bootstrapped and set up with the AWS CDK.

Series Overview

In this chapter, we'll see how the series will flow and tour what we're building. Then we'll set up our CDK project so that it's flexible to iterate on in later chapters.

In particular, here's the following outline for our backend:

1. Understanding if this series is for you

2. Setting up an AWS account and the AWS CDK

3. You are here 👉🏽 Project overview and setup

4. DynamoDB and Lambda: Creating your first CDK services

5. Amazon Cognito: Adding authentication and authorization

6. Simple Storage Service (S3) and Cloudfront: Adding image storage

7. AWS AppSync: Modern API Development

8. Deploying to AWS: CDK context and GitHub actions

Also, because this is a fullstack series, we'll bring our infrastructure to life on the frontend:

1. Frontend setup NextJS, TailwindCSS, and Cloudinary(!)

2. Frontend to backend with AWS Amplify libraries

3. AWS Amplify Hosting: Considerations and walkthrough

[Bonus]: Fullstack SaaS starter with Stripe

With an understanding of what services we'll be making use of, let's get started building our project!

AWS CDK Project Setup

The project we'll build is a trip posting app where we can share with others the trips that we've been on. While sounding simple, take a moment to think about all of the features our app will require and how they match the upcoming chapters. You'll soon realize this is a core functionality found in most modern applications that hope to be more than a public to-do site.

In a new directory, run the following command:

# My direcotry: ~/Projects/fullstack-cdk-series/backend-trip-post
npx aws-cdk@latest init -l typescript

🗒️ For our backend, I'll be working from a backend-trip-post directory.

This will initialize a new CDK project using the latest version. Specifically, we are setting the language to TypeScript (both --language, or -l work).

Once installed, you should receive output similar to the following:

Right away, you can see the CDK is here to inform us of useful commands. To expand on this, open up the project in your editor (I'll be using VS Code) and let's go over a few of the generated files:

• npm run build: We're writing TypeScript, and this command uses tsc to convert it to JavaScript

• npm run watch: Some services like Lambda can be watched and redeployed upon save instead of having a full redeploy

• npm run test: haha lol runs our test suite

• lib/backend-trip-post-stack.ts : In JavaScript, you can call multiple functions at the same time by wrapping them in a larger function. This is where we define that larger function--called a stack.

• bin/backend-trip-post.ts : Our projects can contain multiple stacks. This is where we tell our CDK app instance(new cdk.App())about them. Since AWS has multiple regions around the world and it's possible to deploy our application to various accounts, this is also where we pass that configuration to our stacks. If left blank, it will use the values from our local AWS profile.

In short, what we deploy to AWS is one or many stacks. These stacks can be configured with the account, region, and additional context we provide.

A stack is made up of constructs. But what's a construct?

Constructs

Recall that the AWS CDK is a wrapper around CloudFormation, and that CloudFormation is AWS's way of templating AWS services.

A construct is a wrapper around a CloudFormation-defined AWS service. That means instead of writing YAML, we get to use a TypeScript. These constructs can exist in one of three levels depending on how abstract you want to be.

While sounding (super) confusing at first, as a frontend developer, you're actually already familiar with this concept due to React's components:

In the above screenshot, we see an example of a level 1 construct in purple. The base is HTML, and the abstraction is JSX. At level 1, even though we're in React, our code is mirroring what's available in HTML.

At level two, we use React as intended. When people think of React, this is what typically comes to mind. Instead of mirroring HTML, our JSX has sensible defaults and opinions based on how people are likely to use it.

When we get to level 3 we trade flexibility for speed. This often means we don't have as many knobs to configure but get a solution-oriented abstraction that is usually the combination of other services.

When a new service at AWS comes out, the CDK is typically updated with level 1 support. This is done by pulling the CloudFormation template.

After that, the CDK team and the community can contribute a level 2 construct. This is what most developers prefer to work with, and what we'll be using in this series.

In the CDK, an L3 construct represents a solution. These are community maintained and while they can save a lot of time like deploying a static site with a few commands, they are often org specific in both implementation and what options they allow.

CDK Context: How to avoid pigeonholing

We haven't written much code in this post and that makes me sad. So before wrapping up, let's make our time easier in the later stages by spending some time on our setup.

Similar to React, the CDK doesn't have an opinion on how you set up your project. As many devs know, this is great for getting started but can pigeonhole (put us in a situation difficult to get out of) if not careful.

While we'll be iterating on this process when in the deployment chapter, we can lay the foundation now.

Initial Context

When we initialized our project, the CDK generated a cdk.json file. For the most part, this contains configurations by the CDK and feature flags so that otherwise breaking changes by the CDK team can be safely introduced. However, we can also add additional context fields that are specific to how we would like our app to be deployed.

While it's possible to add those values in this file, I prefer putting them in a separate cdk.context.json file. Create this file in the root of your project:

touch cdk.context.json # or right-click in your editor to create the file.

🗒️ This file is special when placed at the root of our project. The CDK knows how to read the contents of this file as we'll see later on.

In that file, place the following:

{
    "globals": {
        "appName": "travel-viewer-app",
        "region": "us-east-1",
        "appDescription": "A stack for a Travel pic viewer"
    },
    "environments": [
        {
            "environment": "develop",
            "branchName": "develop"
        }
    ]
}

To summarize this code: Anything in globals will be about our project, regardless of what branch or stage we're on. Anything in environments will be specific to the git branch or CDK environment we are targeting.

The CDK initialized a git project for us and so you should be on the main branch currently. That's fine and we'll check out our develop branch later on.

Once we deploy, we'll want to combine our globals with the specific object in our environments array into one complete object.

To make sure we have TypeScript gives us inference on that, add a cdk.context.d.ts file and paste in the following:

export type CDKContext = {
    appName: string
    appDescription: string
    region: string
    environment: envNameContext
    branchName: branchNameContext
}

export type envNameContext = 'develop'

export type branchNameContext = 'develop'

Again, the above snippet refers to the 3 globals and the two environment-specific values.

🗒️ The CDK has type-definition files ignored by default in the .gitignore file. To keep that setting, but allow this file, add the following under the *.d.ts mention:

!cdk.context.d.ts

bin directory setup

This section is crucial to setting up our application for long-term success.

We need a way to get the current git branch we are on. Also, as mentioned, we'll need to combine our context file into a single object. This will be in addition to any additional props our stack needs to get set up.

Doing this in our bin/backend-trip-post.ts would make it a bit messy. So we'll do this in a new file.

Create the following file in our bin directory: init-stack.ts

Once created, import the CDK library and our context types:

import { CDKContext } from '../cdk.context'
import * as cdk from 'aws-cdk-lib'

getCurrentBranch function

// ... other imports
import * as gitBranch from 'git-branch'

// Get the current git branch
const getCurrentBranch = (): string => {
    const currentBranch = gitBranch.sync()
    return currentBranch
}

Getting the branch name is simple enough with the git-branch package. Be sure to install that package and its separately packaged TypeScript types:

npm i git-branch && npm i --save-dev @types/git-branch

getEnvironmentContext function

Next, we'll want to get our branch, and based on that create an object that matches our CDKContext types.

To accomplish that, paste in the following:

// Get the environment context based on the current git branch
const getEnvironmentContext = (app: cdk.App) => {
    const currentBranch = getCurrentBranch()
    const environments = app.node.tryGetContext('environments')
    const environment = environments.find(
        (env: any) => env.branchName === currentBranch
    )
    const globals = app.node.tryGetContext('globals')

    return { ...globals, ...environment }
}

Nothing too fancy here--which is how I like to keep things, but what you'll notice is the app.node.tryGetContext. By defining our context in a cdk.context.json file, we can call this method anywhere in our application to retrieve values. From there, we use a combination of the getCurrentBranch method and the find method on arrays to create our object.

initStack function

The last function in this file is what we'll end up calling in our backend-trip-post.ts file.

Recall that so far we've defined the custom properties that we'll provide to our stack. However, the CDK requires its own set. Specifically, it needs to know the AWS environment to publish our app to, and a name for the stack. Optionally, we can tell it things like what account, tags, and name of the stack.

To see this in action, paste in the following:

// Initialize the stack
export const initStack = () => {
    const app = new cdk.App()
    const context = getEnvironmentContext(app) as CDKContext
    const stackName = `${context.appName}-stack-${context.environment}`

    // tag resources in AWS to find the easier
    const tags = {
        Environment: context.environment,
        AppName: `${context.appName}`,
    }

    // Provide required properties to our Stack
    const stackProps: cdk.StackProps = {
        env: {
            region: context.region,
        },
        stackName: stackName,
        description: context.appDescription,
        tags,
    }

    return {
        app,
        stackNameWithEnv: stackName,
        stackProps,
        context,
    }
}

Passing values to our stack

When the above initStack function gets called it returns everything needed for our stack. Let's complete this post by initializing our stack and updating its values to accept them.

In bin/backend-trip-post.ts replace the existing code so that it resembles the following:

#!/usr/bin/env node
import { initStack } from './init-stack'
import 'source-map-support/register'
import { BackendTripPostStack } from '../lib/backend-trip-post-stack'

const { app, stackNameWithEnv, stackProps, context } = initStack()

const travelStack = new BackendTripPostStack(
    app,
    stackNameWithEnv,
    stackProps,
    context
)

If all went well, you should see TypeScript complaining that BackendTripPostStack doesn't know about context.

Update that file so that the default code is replaced with an updated version that not only takes in our context, but no longer assumes the props are optional:

import { CDKContext } from './../cdk.context.d'
import * as cdk from 'aws-cdk-lib'
import { Construct } from 'constructs'

export class BackendTripPostStack extends cdk.Stack {
    constructor(
        scope: Construct,
        id: string,
        props: cdk.StackProps,
        context: CDKContext
    ) {
        super(scope, id, props)
        // our code will go here
    }
}

Congratulations, you've just completed the hardest part of this entire series 🎉

🗒️ I want to take a moment to emphasize that we didn't have to construct our app like this no more than on the frontend we don't have to split out our code.

However, some things remain true across stacks. Learning how to set up a project based on what you're trying to accomplish is one of them

Conclusion

In this chapter, we talked about how to initialize a CDK project and the various files that come with it. We compared CDK wrapping CloudFormation to JSX wrapping HTML. This analogy extended to constructs being similar to React components before getting our stack set up to accept custom values.

In the next chapter of this series, we'll dive into how simple it can be to work with constructs by creating our databases and a Lambda function.

In the meantime, I'm looking forward to your comments, suggestions, and feedback!

Happy Coding,

🦦

With the CDK, you can use TypeScript to define your cloud infrastructure, including services like Amazon S3, AWS Lambda, and Amazon DynamoDB. By defining your infrastructure in one place, it can be versioned and easily reproduced. This is a huge benefit over clicking through the AWS console.

AWS has a service that already does this: CloudFormation. But it's known for being verbose. The CDK is a wrapper around CloudFormation that also comes with a set of libraries to make it easy to define best practices and security policies for your cloud resources. This means that you can ensure that your infrastructure is secure and follows AWS best practices without having to spend too much time learning about the specifics upfront.

In this post, we'll walk through how to get started with the CDK, starting with creating an AWS user and installing the AWS CLI. In later posts, we'll also deploy services and bring them into our frontend applications.

Prerequisites

• Node.js version 16 or later is installed.

• NPM is installed.

• An AWS account

• https://youtu.be/FAfhMXUiLuU

• https://www.youtube.com/watch?v=UnqxiSJEZAk

Steps

[optional] Creating a New AWS User with Admin Role

First you need to create a new AWS user with the appropriate permissions. Follow these steps to create a new user with the Administrator role and generate an access key and secret access key:

1. Sign in to the AWS Management Console.

2. Navigate to the IAM (Identity and Access Management) service.

3. In the navigation pane, click on Users and then click the Add users button.

4. 

5. Enter a User name and select the Programmatic access checkbox in the "Select AWS access type" section (adding console access is optional but preferred). Click Next: Permissions.

6. You can choose to add the user to an existing group, copy permissions from an existing user, or attach policies directly. For this guide, we will add the user to an existing group. Click the Add user to group tab.

7. Click the Create group button to create a new group with the Administrator role. Enter a name for the group, such as "Admins".

8. In the search bar, type AdministratorAccess and select the checkbox next to the AdministratorAccess policy. Click Create group.

9. You should now see the newly created "Admins" group. Select the checkbox next to the group and click Next: Tags.

10. (Optional) Add any tags you want to associate with the user, then click Next: Review.

11. Review the user details and permissions, then click Create user.

12. After the user is created, you will see the Access key ID and Secret access key for the new user. Important: This is the only time you will be able to view the secret access key, so be sure to download the .csv file or copy the keys to a safe location.

Now that you have created a new AWS user with the Administrator role and obtained the access key and secret access key, you can proceed to configure the AWS CLI using the aws configure command. Enter the access key and secret access key when prompted.

1. Install AWS CLI

Follow the installation instructions from the official AWS documentation.

1. Configure a default AWS profile

To configure your AWS CLI, open a terminal and run the following command:

aws configure

You will be prompted to enter your AWS Access Key ID, AWS Secret Access Key, Default region name, and Default output format. Fill in the details and press Enter.

1. Install AWS CDK using npx

Instead of installing the AWS CDK globally, we will use npx to run the latest version:

npx aws-cdk@latest

1. Bootstrap your environment

Run the following command to bootstrap your environment. This is a one-time-per-region process and essentially authorizes the CDK to deploy resources on your behalf:

npx aws-cdk bootstrap

1. Initialize a new CDK project with TypeScript

Create a new directory for your CDK project and navigate to it:

mkdir my-cdk-project
cd my-cdk-project

Note: Initializing a new CDK project should be done in an empty directory.

Now, initialize the new CDK project with TypeScript:

npx aws-cdk init --language typescript

Running CDK commands

Whenever you need to run CDK commands, use npx aws-cdk:

npx aws-cdk <command>

For example, to list your CDK stacks:

npx aws-cdk list

To synthesize your CDK app:

npx aws-cdk synth

Now you have successfully installed AWS CDK version 2 with NPM, configured the AWS CLI, and initialized a new CDK project with TypeScript.

If wanting to destroy your CDK app:

npx aws-cdk destroy

Conclusion

That's it! You have successfully installed AWS CDK version 2 with NPM and configured it for use with the AWS CLI.

In the next post, we'll create our first AWS services

Happy coding🦦

They're usually a group of 1-5 individuals with skills that vary across the development stack. From what I've noticed lately, the trend seems to be that individuals are increasingly frontend developers with a knack for backend development.

What's interesting about this group is their tenacity. They build, get stuck, problem-solve, and listen to their customers to figure out what's next in the pipeline. If I had to make a few more generalizations it's that they favor speed, a good DX, and are not afraid of delivering something less than perfect if it still means delivering something.

This group is constantly seeking ways to optimize its workflow and create powerful, scalable applications that delight customers. While there are lots of frontend frameworks that help with this, some more than others are standing out on the frontend: React/NextJS, Stripe, TailwindCSS, and TypeScript.

The backend is where I see the most decision paralysis. Rightfully so: authN/authZ, file storage, database flexibility, and an API are common to every real-world app, and not always easy to migrate from when needing to. This often leads to picking what is easiest to get started with.

However, while many devs/founders consider the day 1 experience or the first 100 customers, it's important to think about day 100 or how things look when you have 1000 customers. When set up correctly, you sleep all the same.

There are lots of players and opinions in this space, but in this post, we'll discuss why embracing AWS, specifically a core selection of tools and services, can not only unlock your full-stack potential but also elevate your application development so that your customers benefit from it.

So, why should you build your next application on AWS? Here are some compelling reasons and services that you should consider:

Slightly More Technical Overhead, But Worth It

Adopting this AWS-based stack might come with slightly more technical overhead compared to your current workflow. However, the numerous benefits it offers far outweigh this factor. By diving into the AWS ecosystem, you'll gain access to a world of powerful services and tools, enabling you to build highly-scalable, cost-effective applications with ease. It's important to note that you developing on AWS doesn't mean using all of the 200+ services they offer. Instead, it's about picking the right service for your particular need.

The added technical overhead will be a valuable investment in your skillset, making you a more versatile developer. As you become proficient in AWS services, you'll find that the initial learning curve pays off in the long run, helping you create more sophisticated applications and positioning you for greater opportunities in the tech industry.

Cost-effective compared to 3rd-party low-code tools

While low-code tools with monthly subscriptions may seem tempting due to how easy they are to get started, AWS offers a more cost-effective and flexible solution when making the most of serverless/managed services. With those, you only pay for the resources you consume, allowing you to optimize costs as your application scales.

That isn't to say low-code tools don't have their place or benefit. Rather, it's about retaining ownership, and thus having more control over what is happening in your application. Recall that AWS is an ecosystem of services. Having services that know how to talk to and integrate is a huge benefit. In the end, low-code tools remain extremely viable (AWS has several), and when considering a 3rd-party tool, there is of "Better-Together" workflow as well.

Bias Towards Serverless & Managed Services

Touched on above, but focusing on serverless and managed services offered by AWS enables you to build scalable, cost-effective applications without managing servers. I think it seems fair: If I'm not using a service, then don't charge me.

AWS offers a range of serverless services like AWS Lambda, Amazon API Gateway, and Amazon DynamoDB, allowing you to build and deploy your applications quickly, with built-in scalability and cost optimization.

As an indie creator or SaaS founder, cost and durability are likely your biggest factors. This is where a managed service comes into play. Managed means less time provisioning throughput, less code you have to write, and more time focusing on your product and customers.

When I tell folks that, they often think this means more Lambda functions. I'm saying fewer Lambda functions. A large benefit of serverless, fully-managed services on AWS is there are often direct integrations available so they can talk to one another. Less Lambda functions mean fewer cold starts.

AWS StepFunctions, EventBridge Pipes, and AWS AppSync are great examples of this.

Increased earning potential

I've been speaking from the perspective of an indie creator or SaaS founder, and while that's intentional, I wanted to add this blurb before getting into the stack itself.

Maybe the product is you and you're consulting or offering time-based services. Learning AWS can significantly boost your earning potential. As one of the most in-demand cloud platforms, having AWS skills on your resume can open up lucrative opportunities in the job market. You don't need to have every certification, or even be some AWS guru. You can still position yourself as an invaluable full-stack developer, ready to tackle complex projects and contribute to the growth of startups and SaaS businesses.

Ok, so if you've made it this far, you may be wondering what a fullstack project on AWS looks like and of the 200+ services, which ones are core for most SaaS apps and indie creators.

Let's discuss it!

Modern Frontend Development with NextJS and Tailwind

With almost half of all respondents in the 2022 State of JS survey using NextJS and a 90% retention rate, NextJS has become the staple when it comes to application development.

Embracing modern frontend development means adopting powerful tools like NextJS and Tailwind CSS. NextJS, a popular framework built on top of React, brings numerous benefits, such as built-in TypeScript support, which enables robust type-checking and code autocompletion, and file-based routing for effortless page creation and navigation. With its hybrid rendering, you choose between server-side rendering (SSR), static site generation (SSG), or client-side rendering, depending on your application's needs.

With 46% of the State of CSS survey respondents using Tailwind, and the highest retention rate (79%) of CSS frameworks, Tailwind should be your default CSS framework when building new applications.

Tailwind CSS is a utility-first CSS framework that streamlines the styling process, making it faster and more efficient. It promotes consistency, maintainability, and readability, allowing you to create responsive, modern designs without writing custom CSS classes. By combining NextJS and Tailwind CSS, you can build high-performance, visually appealing applications while benefiting from an enhanced development experience that keeps you focused on what truly matters: delivering innovative solutions for your customers.

Low Barrier-to-Entry with AWS CDK and TypeScript

While not showcasing every option available, the above image shows everything required to create a database and an S3 bucket that stores files.

As a TypeScript enthusiast, you'll love working with the AWS Cloud Development Kit (CDK). Before, creating your AWS Services by clicking through the AWS Console and writing down the steps you took so you didn't forget them next time. When scripting came along, it was either writing your own Bash scripts to use the AWS CLI or writing verbose templates using AWS CloudFormation.

If you haven't used CloudFormation before, just know defining a database like the above was with a YAML file several times longer.

With the AWS CDK, you can create, test, and deploy AWS resources a lot easier, streamlining your development process and taking advantage of the full power of AWS services since it exists as a wrapper around CloudFormation.

The AWS CDK ranks 3rd when it comes to building out fully serverless applications, has the highest retention (84%), and has the best positive/negative split.

Simple Frontend-Backend Integration with AWS Amplify

AWS Amplify is a suite of services that include a CLI, hosting platform, UI Component Library and more. In particular, the Amplify JavaScript libraries provide a seamless way to connect your frontend and backend, offering pre-built UI components, authentication, and storage solutions.

As an example, developers often have to figure out an easy way to pass a large file from the frontend to some backend storage service. Using the Amplify libraries, files can several GB large and can be sent as a multi-part upload, paused, resumed and canceled.

Scalable, Real-Time GraphQL API with AWS AppSync

As a frontend developer, you're probably familiar with the benefits of GraphQL, offering a flexible and efficient way to fetch data.

AWS AppSync is a fully managed GraphQL service. You supply it with a schema, give it data sources, and tell it how to connect to the data sources. As more requests come in, the service scales appropriately. If you've ever had Taco Bell delivered to you, watched a show on HBO Max, saw stats on a live Ferrari F1 race, or purchased a ticket from Ticketmaster, then you've already interacted with AppSync.

To resolve the data, you write JavaScript (native TypeScript support coming soon). Note that this isn't in a server, or even a serverless function like Lambda, this is a mapping that tells AppSync how to fetch the data. For example, the following is how a user would grab an item from DynamoDB:

To emphasize, when a user on the frontend makes a request, that request goes to AppSync, which then, gets the data directly from DynamoDB. No connections to manage, to extra service to invoke. This is the power of having various resources as part of the same ecosystem of services.

To go in the other direction, by specifying the @aws_cognito_user_pools directive on your schema, AppSync will automatically inspect the JWT of the request to make sure the user is authenticated with Amazon Cognito before allowing the request.

Indie creators and SaaS founders of all sizes often have changing requirements and unforeseen access patterns to account for. AppSync's flexible schema model means less stress and more innovation.

I've written a lot about AppSync on this blog and the official AWS blog, so feel free to check out that content if interested in a deeper discussion!

Conclusion

Adopting AWS for your application development brings a lot of benefits, including a more streamlined and efficient development process. By leveraging the AWS CDK for TypeScript, serverless and managed services, AWS AppSync for GraphQL, and AWS Amplify for frontend-backend integration, you can fully take advantage of your full-stack potential and build innovative, scalable applications.

This is the first post in a series where I'll walk you through building a full-stack application using the tools and services we discussed. I'll show you how to get started, from setting up your AWS environment to deploying your NextJS application backed by core AWS services. By the end, you'll have the confidence and experience to scaffold out your next great idea on AWS,

See you there!

- 🦦