DEV Community: Coner Murphy

How to Build Your Own ChatGPT Clone Using React & AWS Bedrock

Coner Murphy — Wed, 01 May 2024 17:21:40 +0000

Over the last few months, AI-powered chat applications like ChatGPT have exploded in popularity and have become some of the largest and most popular applications in use today. And, for a lot of people, they may have an air of mystery and wonder about how they work. So, to help remove that, in today’s post, we’re going to look at building a ChatGPT-inspired application called Chatrock that will be powered by Next.js, AWS Bedrock & DynamoDB, and Clerk.

Below is a sneak peek of the application we’re going to end up with at the end of this tutorial so without further ado, let’s jump in and get building!

Tech Stack Breakdown

But, before we jump in and start writing code for our application, let’s take a quick look at the tech stack we’ll be using to build our app so we can get familiar with the tools we’ll be using to build Chatrock.

Next.js

Next.js has long cemented itself as one of the front runners in the web framework world for JavaScript/TypeScript projects so we’re going to be using that. More specifically we’re going to be using V14 of Next.js which allows us to use some exciting new features like Server Actions and the App Router.

Finally, for our front end, we’re going to be pairing Next.js with the great combination of TailwindCSS and shadcn/ui so we can focus on building the functionality of the app and let them handle making it look awesome!

Clerk

Of course, we’ll need some authentication with our application to make sure the queries people ask stay private. And, because authentication is notoriously finicky and potentially problematic to add we’re going to be using Clerk. And, as we’ll see later on when we start building our application and adding the auth in, Clerk makes it super effortless to implement high-quality and effective authentication to Next.js projects.

AWS

The final large piece of the tech stack that we’ll focus on in this section is AWS. Now, we won’t be using all of the services AWS offers (I’m not sure if this is possible) but instead, we’re going to be using two in particular.

The first is AWS DynamoDB which is going to act as our NoSQL database for our project which we’re also going to pair with a Single-Table design architecture.

The second service is what’s going to make our application come alive and give it the AI functionality we need and that service is AWS Bedrock which is their new generative AI service launched in 2023. AWS Bedrock offers multiple models that you can choose from depending on the task you’d like to carry out but for us, we’re going to be making use of Meta’s Llama V2 model, more specifically meta.llama2-70b-chat-v1.

Prerequisites

With the overview of our tech stack out of the way, let’s take a quick look at the prerequisites that we’ll need for this project. First of all this tutorial isn’t intended as a Next.js tutorial so if you’re not comfortable working in Next.js or using some of their newer features like the App Router or Server Actions, take a look at their docs, and once you’re comfortable with them, return to this tutorial and carry on building!

Secondly, you’ll need an AWS account to deploy the DynamoDB database we’ll define to as well as give you access to Bedrock. Once you have your AWS account, you’ll need to request access to the specific Bedrock model we’ll be using (meta.llama2-70b-chat-v1), this can be quickly done from the AWS Bedrock dashboard.

NOTE: When requesting the model access, make sure to do this from the us-east-1 region as that’s the region we’ll be using in this tutorial.

While you’re in the AWS dashboard, if you don’t already have an IAM account configured with API keys, you’ll need to create one with these so you can use the DynamoDB and Bedrock SDKs to communicate with AWS from our application. Read how to generate API keys for an IAM user on their docs.

Finally, once you have your AWS account set up and working, you’ll need to configure the AWS CDK on your local machine to allow you to deploy the DynamoDB database we’ll configure in this project. Check out the docs to learn how to do this.

Getting Started

Now, with the tech stack and prerequisites out of the way, we’re ready to get building! The first thing you’ll want to do is clone the starter-code branch of the Chatrock repository from GitHub. You’ll then want to install all of the dependencies by running npm i in your terminal inside both the root directory and the infrastructure directory.

Inside this branch of the project, I’ve already gone ahead and installed the various dependencies we’ll be using for the project. I’ve also configured some boilerplate code for things like TypeScript types we’ll be using as well as some Zod validation schemas that we’ll be using for validating the data we return from DynamoDB as well as validating the form inputs we get from the user. Finally, I’ve also configured some basic UI components we’ll be using from shadcn/ui.

Once you have the project cloned, installed, and ready to go, we can move on to the next step which is configuring our AWS SDK clients in the Next.js project as well as adding some basic styling to our application.

Setting Up Our AWS SDK Clients

To configure the AWS SDK clients in our project, create a new file in the root of the project called config.ts and then add the below code to it.

import { BedrockRuntimeClient } from "@aws-sdk/client-bedrock-runtime";
import { DynamoDB } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocument } from "@aws-sdk/lib-dynamodb";

const awsConfig = {
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID || "",
    secretAccessKey: process.env.AWS_SECRET_KEY_VALUE || "",
  },
  region: process.env.AWS_API_REGION || "",
};

export const db = DynamoDBDocument.from(new DynamoDB(awsConfig), {
  marshallOptions: {
    convertEmptyValues: true,
    removeUndefinedValues: true,
    convertClassInstanceToMap: false,
  },
});

export const bedrock = new BedrockRuntimeClient({
  ...awsConfig,
  region: "us-east-1",
});

What this code does is export two clients (db and bedrock), we can then use these clients inside our Next.js Server Actions to communicate with our database and Bedrock respectively.

Finally, to complete the setup of our AWS clients we need to add some ENVs to our project. In the root of your project create a new file called .env.local and add the below values to it, make sure to populate any blank values with ones from your AWS dashboard.

# AWS

# API Key ID and Value from your IAM account
AWS_ACCESS_KEY_ID=""
AWS_SECRET_KEY_VALUE=""

# Set this to the default AWS region your account was configured for on your local machine earlier.
AWS_API_REGION=""

DB_TABLE_NAME=ChatRockDB

Deploying the Database

With our AWS SDK clients now configured and ready to go, we’re ready to deploy our DynamoDB database for our project. To do this, replace the contents of the file ./infrastructure/lib/chatrock-infrastructure-stack.ts with the below code.

import * as cdk from "aws-cdk-lib";
import { AttributeType, BillingMode, Table } from "aws-cdk-lib/aws-dynamodb";
import { Construct } from "constructs";

export class ChatRockIntfrastructureStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // Create a new DynamoDB instance that is set to use on-demand billing and to be removed when the stack is destroyed
    new Table(this, "ChatRockDB", {
      partitionKey: { name: "pk", type: AttributeType.STRING },
      sortKey: { name: "sk", type: AttributeType.STRING },
      billingMode: BillingMode.PAY_PER_REQUEST,
      tableName: "ChatRockDB",
      removalPolicy: cdk.RemovalPolicy.DESTROY,
    });
  }
}

In this code, we define a new DynamoDB database that is configured to use on-demand billing as well as to be destroyed when the CDK stack is destroyed.

To deploy the database to AWS, run the command cdk deploy in your terminal inside the infrastructure directory and accept any prompts you’re given. Then once complete your new database called ChatRockDB should be deployed and ready to go! With the database sorted, we’re now ready to jump into Next.js and start building our application, let’s do this!

Adding Some Basic Styling

The first thing we’re going to do in our application is take care of some housekeeping and add some basic styles as well as create a new component for the icon we’ll be using. To create the icon component, create a new file at ./components/icon.tsx and add the below code to it.

import { IoMdChatbubbles } from "react-icons/io";

export function Icon() {
  return (
    <div className="flex flex-row gap-3 items-center">
      <div className="bg-stone-50 p-2 rounded-lg shadow-md">
        <IoMdChatbubbles className="text-4xl text-violet-500" size={24} />
      </div>
    </div>
  );
}

With our Icon component now created (we’ll need this in a moment for our custom sign-in and sign-up pages). We’re going to quickly turn our attention to the ./app/layout.tsx file and update it to look like the code below.

import type { Metadata } from "next";
import { Inter as FontSans } from "next/font/google";
import "./globals.css";
import { cn } from "@/lib/utils";

export const fontSans = FontSans({
  subsets: ["latin"],
  variable: "--font-sans",
});

export const metadata: Metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body
        className={cn(
          "flex flex-row min-h-screen bg-background font-sans antialiased text-stone-700 bg-slate-100",
          fontSans.variable
        )}
      >
        <div className="min-w-max w-full h-screen overflow-y-auto">
          {children}
        </div>
      </body>
    </html>
  );
}

In this code, we’ve updated the base styles of our entire project to give us a good base to build off in the coming sections when we look at adding in our authentication with Clerk as well as building out the sidebar that will allow users to switch between the various conversations they have as well as sign out. So, let’s take a closer look at both of those next.

Adding Authentication with Clerk

Before we can look at implementing Clerk into our project and using it to protect our application, we first need to configure our application on Clerk’s dashboard. So, if you don’t already have a Clerk account, head over to their dashboard and sign up for one.

Once you’ve signed into your account, we’ll need to create a new application, for our project, we won’t be using any social auth providers and will be keeping it fairly basic with just the “Email” sign-in option they provide. So, for now just select “Email”, give your application a name (”Chatrock”), and then click “Create application”.

Then once you’re on the Clerk dashboard for your application, we need to enable the option for users to have the optional choice to provide us with their name so we can display it on our application’s sidebar when they’re logged in. To enable this option, click on “User & Authentication”, then “Email, Phone, Username” and then scroll down to the “Personal Information” section where you can toggle “Name” on and then press “Apply changes”.

Finally, in the Clerk dashboard, click on “API Keys” on the sidebar and then copy the ENV values shown to you, (make sure that Next.js is selected on the dropdown).

Adding Clerk to Our Application

Now, at this point, we’ve configured our Clerk application on the dashboard and have copied the ENVs that we will need inside our app so we’re now ready to integrate Clerk into our app!

To do this, first, paste the ENVs you copied from the Clerk dashboard into your .env.local file from earlier so it now looks something like this.

# AWS

# API Key ID and Value from your IAM account
AWS_ACCESS_KEY_ID=""
AWS_SECRET_KEY_VALUE=""

# Set this to the default AWS region your account was configured for on your local machine earlier.
AWS_API_REGION=""

DB_TABLE_NAME=ChatRockDB

# CLERK

# Values from your Clerk dashboard
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=""
CLERK_SECRET_KEY=""

With these ENVs added we can now setup Clerk in our application to provide authentication to our users. To do this, we’ll need to wrap our application in the ClerkProvider component from the @clerk/nextjs package, we can do this by updating our ./app/layout.tsx file from earlier. Below is what your code should now look like with this added.

import type { Metadata } from "next";
import { Inter as FontSans } from "next/font/google";
import "./globals.css";
import { cn } from "@/lib/utils";
import { ClerkProvider } from "@clerk/nextjs";

export const fontSans = FontSans({
  subsets: ["latin"],
  variable: "--font-sans",
});

export const metadata: Metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <ClerkProvider>
      <html lang="en">
        <body
          className={cn(
            "flex flex-row min-h-screen bg-background font-sans antialiased text-stone-700 bg-slate-100",
            fontSans.variable
          )}
        >
          <div className="min-w-max w-full h-screen overflow-y-auto">
            {children}
          </div>
        </body>
      </html>
    </ClerkProvider>
  );
}

With our application now wrapped in the ClerkProvider, we’ve almost configured our application to have authentication using Clerk. The final thing we need to do is to enforce the authentication in our app by adding a custom middleware.ts file to our project. To do, this create a new middleware.ts file in the root of your project and add the below code to it.

import { authMiddleware } from "@clerk/nextjs";

export default authMiddleware({});

export const config = {
  matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
};

Now, with this custom middleware added, our application enforces authentication and if you were to start your application by running npm run dev in the root directory and visit the app on http://localhost:3000 you would be redirected to the Clerk sign-up page where you could sign up for an account. Then after signing up for an account, you would be redirected back to the home page of our application.

Adding Custom Sign-In and Sign-Up Pages

Now, while I love the ease and simplicity of Clerk’s hosted sign-in and sign-up pages sometimes you will want custom sign-in and sign-up pages to give your user a cohesive experience from start to finish when using your app. So, what we’re going to do now is to create some custom sign-up and sign-in pages that utilize Clerk’s pre-built auth components (SignIn and SignUp).

The first thing we’ll need to do to create our custom sign-up and sign-in pages is to create the pages in our Next.js application. To do this, create a new file at ./app/sign-up/[[...sign-up]]/page.tsx and at ./app/sign-in/[[...sign-in]]/page.tsx and add the below code to them respectively.

import { Icon } from "@/components/icon";
import { SignUp } from "@clerk/nextjs";
import Link from "next/link";

export default function Page() {
  return (
    <div className="h-screen flex flex-col items-center justify-center gap-6 min-w-full">
      <Icon />
      <h2 className="text-2xl font-semibold text-gray-800">
        Sign up for a new account
      </h2>
      <SignUp
        appearance={{
          elements: { footer: "hidden", formButtonPrimary: "bg-violet-700" },
        }}
      />
      <div className="flex flex-row gap-1 text-sm">
        <p>Already a user?</p>
        <Link
          href="/sign-in"
          className="text-violet-700 underline font-semibold"
        >
          Sign in here.
        </Link>
      </div>
    </div>
  );
}

import { Icon } from "@/components/icon";
import { SignIn } from "@clerk/nextjs";
import Link from "next/link";

export default function Page() {
  return (
    <div className="h-screen flex flex-col items-center justify-center gap-6 min-w-full">
      <Icon />
      <h2 className="text-2xl font-semibold text-gray-800">
        Sign in to your account
      </h2>
      <SignIn
        appearance={{
          elements: { footer: "hidden", formButtonPrimary: "bg-violet-700" },
        }}
      />
      <div className="flex flex-row gap-1 text-sm">
        <p>Not a user?</p>
        <Link
          href="/sign-up"
          className="text-violet-700 underline font-semibold"
        >
          Sign up here.
        </Link>
      </div>
    </div>
  );
}

You can see both of these pages are quite similar in structure, they show the Icon component we made earlier before then showing a title and rendering their respective pre-built Clerk component (SignIn or SignUp) from the @clerk/nextjs package. At this point, we also perform some minor customizations to the Clerk components to make sure they fit in with our branding a bit better by updating their colors.

Finally, we then render a custom footer to our page which helps users navigate between our sign-up and sign-in pages if they want to change between them at any point.

With our custom pages now built, we have two more things we need to do before our custom authentication pages are ready to go. First of all, we need to update our .env.local file from earlier to add in some custom ENVs for the pre-built Clerk components to utilize. Add these ENVs under the ones you added for Clerk earlier on.

# Other Clerk and AWS ENVs...

NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/

Finally, the last thing we need to do is to update our middleware.ts file to ensure that the new sign-in/up pages aren’t placed behind our authentication and are made public so anyone can access them. To do this, update your middleware.ts file to look like below.

import { authMiddleware } from "@clerk/nextjs";

export default authMiddleware({
  // Note this line where we've defined our auth pages as public routes to opt-out of authentication
  publicRoutes: ["/sign-in", "/sign-up"],
});

export const config = {
  matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
};

Our new custom sign-in/up pages are now complete and if you still have your development server running, visit one of the pages and enjoy the new designs we’ve implemented!

NOTE: If you signed up for an account using the Clerk-hosted pages, you won’t be able to sign out of the application at the moment (we’re implementing this in the next section) so if you’d like to check out the new sign in/up pages before then, use private browsing, a different browser, or clear your sessions in the browser’s dev console.

Finishing the Application’s Layout

Now with our authentication setup, let’s take a look at implementing the last piece of our application’s layout, the sidebar. This sidebar will contain two important pieces of functionality, the first is the conversation history of the currently authenticated user which will allow them to switch between different conversations they’ve had. The second is the UserButton component from Clerk which will give users an easy way to sign out of the application.

Conversation History

Let’s start by building the conversation history functionality and UI before then tying it together with the UserButton component in a new custom sidebar.tsx file we’ll create.

To build our conversation history functionality we’ll need to create a couple of Server Actions (getAllConversations and deprecateConversation), the purpose of both of these should be fairly self-explanatory but we’re going to use the getAllConversations action to give us a list of all of the user’s conversations to map over and act as links on the sidebar. Then for each conversation, we’re going to offer the ability to “delete” it using the deprecateConversation Server Action.

NOTE: I’ve put delete in quotations because although it’ll appear to the user that we’re deleting the conversation we're actually performing a soft-delete and just marking the item as DEPRECATED in the database and only showing them ACTIVE ones on the front end.

With the overview of this functionality covered, let’s jump in and get building. So, as mentioned earlier we’re going to be starting by making the new Server Actions, to do this, create a new directory inside the app directory called actions and then another new one inside that called db. Then inside the db directory create two new files called get-all-conversations.ts and deprecate-conversation.ts. Then add the respective code below to each of them.

"use server";

import { db } from "@/config";
import { conversationSchema } from "@/schema";
import { QueryCommand } from "@aws-sdk/lib-dynamodb";
import { currentUser } from "@clerk/nextjs";

export const getAllConversations = async (includeDeprecated = false) => {
  const currentUserData = await currentUser();

  try {
    // Get the first 100 conversations for the current user from the DB
    const { Items } = await db.send(
      new QueryCommand({
        TableName: process.env.DB_TABLE_NAME,
        ExpressionAttributeValues: {
          ":pk": `USER#${currentUserData?.id}`,
          ":sk": "CONVERSATION#",
        },
        KeyConditionExpression: "pk = :pk AND begins_with(sk, :sk)",
        Limit: 100,
      })
    );

    const parsedPrompts = conversationSchema.array().nullish().parse(Items);

    // If the request wants to return deprecated ones, return all data
    if (includeDeprecated) {
      return parsedPrompts;
    }

    // Otherwise filter for just active ones and return them
    return parsedPrompts?.filter((prompt) => prompt.status === "ACTIVE");
  } catch (error) {
    console.error(error);
    throw new Error("Failed to fetch all conversations");
  }
};

"use server";

import { db } from "@/config";
import { UpdateCommand } from "@aws-sdk/lib-dynamodb";
import { currentUser } from "@clerk/nextjs";

export const deprecateConversation = async (uuid: string) => {
  const currentUserData = await currentUser();

  try {
    // To mark an item as deleted we use "soft deletes" so we update the item status to be "DEPRECATED" and then filter these out when fetching data
    await db.send(
      new UpdateCommand({
        TableName: process.env.DB_TABLE_NAME,
        Key: {
          pk: `USER#${currentUserData?.id}`,
          sk: `CONVERSATION#${uuid}`,
        },
        UpdateExpression: "SET #status = :status",
        ExpressionAttributeNames: {
          "#status": "status",
        },
        ExpressionAttributeValues: {
          ":status": "DEPRECATED",
        },
      })
    );
  } catch (error) {
    console.log(error);
    throw new Error("Failed to deprecate conversation");
  }
};

Conversation History

With our Server Actions now written for our conversation history functionality, let’s build the UI for it. To do this, we’re going to create a new component called ConversationHistory, to add this component, create a new file at ./components/conversation-history.tsx and then add the below code to it.

"use client";

import Link from "next/link";
import { useEffect, useState } from "react";
import { getAllConversations } from "@/app/actions/db/get-all-conversations";
import { z } from "zod";
import { conversationSchema } from "@/schema";
import { usePathname, useRouter } from "next/navigation";
import { IoTrashBin } from "react-icons/io5";
import { deprecateConversation } from "@/app/actions/db/deprecate-conversation";

export default function ConversationHistory() {
  const pathname = usePathname();
  const router = useRouter();
  const [deleting, setDeleting] = useState(false);
  const [prompts, setPrompts] = useState<
    z.infer<typeof conversationSchema>[] | null
  >();

  // When the pathname or the deleting state changes, fetch all of the conversations from the DB and update the state
  useEffect(() => {
    const fetchPrompts = async () => {
      setPrompts(await getAllConversations());
      setDeleting(false);
    };

    fetchPrompts();
  }, [pathname, deleting]);

  return (
    <div className="flex flex-col gap-2 grow">
      {prompts?.map((prompt) => {
        const uuid = prompt.sk.split("#")[1];

        return (
          <div
            className="relative flex flex-row justify-start items-center group bg-slate-200 p-2 py-2.5 rounded-sm text-sm hover:bg-slate-100 transiiton-all ease-in-out duration-300"
            key={prompt.sk}
          >
            <Link href={`/${uuid}`}>
              <span className="w-24 overflow-hidden whitespace-nowrap">
                {prompt.title}
              </span>
            </Link>
            <button className="absolute right-0 mr-2 opacity-0 group-hover:opacity-100 bg-red-400 p-2 rounded-sm transition-all ease-in-out duration-300">
              <IoTrashBin
                onClick={async () => {
                  await deprecateConversation(uuid);
                  setDeleting(true);

                  router.push("/");
                }}
              />
            </button>
          </div>
        );
      })}
    </div>
  );
}

You can see in this code, that we fetch all of the current user’s conversations when the pathname updates or the deleting state changes, we then map over their conversations and display a Link for each of them that will take the user to the conversation's respective page (we’ll create this later on). Then finally we display a button that appears on hover and when clicked will trigger our deprecateConversation functionality and remove the conversation from the view of the user.

Sidebar

With our conversation history functionality now complete we can turn our attention to building the sidebar itself and adding in the UserButton component from Clerk that we mentioned earlier. To add this component, create a new file at ./components/sidebar.tsx and add the below code to it.

import { UserButton, currentUser } from "@clerk/nextjs";
import { Icon } from "./icon";
import Link from "next/link";
import ConversationHistory from "./conversation-history";
import { IoAddOutline } from "react-icons/io5";

export async function Sidebar() {
  const currentUserData = await currentUser();

  // If the user data is falsy, return null. This is needed on the auth pages as the user is authenticated then.
  if (!currentUserData) {
    return null;
  }

  // If the user gave us their name during signup, check here to influence styling on the page and whether we should show the name
  const hasUserGivenName =
    currentUserData.firstName && currentUserData.lastName;

  return (
    <aside className="flex flex-col justify-start min-h-screen w-full py-6 px-8 max-w-60 bg-slate-300 border-r-2 border-r-slate-500 gap-12">
      <header className="flex flex-row gap-2 justify-between items-center">
        <Link href="/" className="flex flex-row gap-2 items-center">
          <Icon />
          <p className="text-gray-700 font-bold">Chatrock</p>
        </Link>
        <Link
          href="/"
          className='flex flex-row justify-start items-center group bg-slate-200 p-2 h-max rounded-sm hover:bg-slate-100 transiiton-all ease-in-out duration-300"'
        >
          <IoAddOutline />
        </Link>
      </header>

      <ConversationHistory />
      <footer
        className={`w-full flex flex-row ${
          !hasUserGivenName && "justify-center"
        }`}
      >
        <UserButton
          afterSignOutUrl="/sign-in"
          showName={Boolean(hasUserGivenName)}
          appearance={{
            elements: { userButtonBox: "flex-row-reverse" },
          }}
        />
      </footer>
    </aside>
  );
}

Now, with this component, we do a few things, first of all, we fetch the current user from Clerk using the currentUser() function. We then check if there is data for the current user and if not we return null. This is important because on non-authenticated pages like the sign-in and sign-up, we will want to return null as there is no current user, this will prevent the sidebar from rendering on the page.

Then we check if the current user gave us their name during the signup flow and store that in the hasUserGivenName variable which we then use to control the displaying of the user’s name in the UserButton component as well as some styling on the sidebar.

Finally, we render out the component which starts by creating a small header section with the Chatrock name and Icon component as well as an “Add” (+) button that allows users to start a new conversation by being redirected to the home page.

We then render out the ConversationHistory component we created a moment ago before finishing the component with a custom footer that contains the UserButton component from Clerk that displays the user’s name if they gave it to us and allows them to sign out of the application.

With our Sidebar component now created the last thing we need to do is add it to our layout.tsx file from earlier so it shows on every authenticated page. To do this, update your ./app/layout.tsx file to look like the one below.

import type { Metadata } from "next";
import { Inter as FontSans } from "next/font/google";
import "./globals.css";
import { cn } from "@/lib/utils";
import { ClerkProvider } from "@clerk/nextjs";
import { Sidebar } from "@/components/sidebar";

export const fontSans = FontSans({
  subsets: ["latin"],
  variable: "--font-sans",
});

export const metadata: Metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <ClerkProvider>
      <html lang="en">
        <body
          className={cn(
            "flex flex-row min-h-screen bg-background font-sans antialiased text-stone-700 bg-slate-100",
            fontSans.variable
          )}
        >
          <Sidebar />
          <div className="min-w-max w-full h-screen overflow-y-auto">
            {children}
          </div>
        </body>
      </html>
    </ClerkProvider>
  );
}

Building the Home page

At this point, we now have a completed application shell that a user can use to sign in and out of the application freely as well as the functionality to show a user’s conversation history. So, now let’s work on adding in the functionality to allow users to create new conversations which is where the home page comes in.

But before we jump into building the functionality let’s take a moment to explore the flow of how this should work. When the user logs into the application they will be taken to the home page that will show an input field allowing them to ask something to the AI, when they fill in this input and submit it, we’ll create a new conversation in the database, generating a new UUID for the conversation. We’ll then return this UUID to the front end and redirect the user to that conversation’s specific page where the AI will then be triggered to reply and then the user can reply and so on.

So, for the home page, we need to add in the functionality to allow users to enter a new prompt and then have that input stored in the database before redirecting the user to the newly created conversation’s page (which will 404 for the moment as we’re going to create this in the next section).

Implementing The Functionality

So, now we know what we’re building for the home page, let’s get started building. The first thing we’re going to do is create the new Server Action that’ll allow us to create new conversations in the database. To create this, create a new file in the ./app/actions/db directory from earlier called create-conversation.ts and add the below code.

"use server";

import { db } from "@/config";
import { conversationSchema } from "@/schema";
import { IPromptStatus } from "@/types";
import { PutCommand } from "@aws-sdk/lib-dynamodb";
import { currentUser } from "@clerk/nextjs";
import { randomUUID } from "crypto";

export const createConversation = async (prompt: string) => {
  const currentUserData = await currentUser();

  if (!currentUserData) {
    throw new Error("User not found");
  }

  // Generate a randomUUID for the new conversation this will be used for the page UUID
  const uuid = randomUUID();
  const conversationUuid = `CONVERSATION#${uuid}`;

  // Build the input for creating the new item in the DB
  const createBody = {
    pk: `USER#${currentUserData?.id}`,
    sk: conversationUuid,
    uuid,
    createdAt: new Date().toISOString(),
    updatedAt: new Date().toISOString(),
    title: `${prompt.slice(0, 20)}...`,
    conversation: [
      {
        author: `USER#${currentUserData?.id}`,
        content: prompt,
      },
    ],
    status: IPromptStatus.ACTIVE,
  };

  try {
    // Create the item in the DB using the prepared body
    await db.send(
      new PutCommand({
        TableName: process.env.DB_TABLE_NAME,
        Item: createBody,
        ReturnValues: "ALL_OLD",
      })
    );

    // Return the created data to the frontend
    return conversationSchema.parse(createBody);
  } catch (error) {
    console.error(error);
    throw new Error("Failed to create conversation");
  }
};

Then with our Server Action created, we can move on to building the frontend UI elements to interact with it. The main UI element we need to build is the input that is shown at the bottom of the screen as this is where the user will input their query before it is sent to the Server Action above for processing.

In our application, we’re going to have two forms, one on the home page and one on the individual conversation page. For the most part, these forms are going to be identical with the only differences being in the onSubmitHandler function they run when the user submits the form.

So, keeping this in mind and to reduce the duplication of code, we’re going to build a generic version of the input field component called GenericPromptInput and then we’re going to build a wrapper of this called HomePromptInput that will add in the custom onSubmitHandler we need for the home page.

With that explanation out of the way, let’s get started building our GenericPromptInput component, to create this add a new file at ./components/prompt-inputs/generic.tsx and add the below code to it.

"use client";

import { Button } from "../ui/button";
import { Input } from "../ui/input";
import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { promptFormSchema } from "@/schema";
import { PromptFormInputs } from "@/types";

interface IProps {
  isGenerating?: boolean;
  onSubmitHandler: (data: PromptFormInputs) => Promise<void>;
}

export function GenericPromptInput({
  isGenerating = false,
  onSubmitHandler,
}: IProps) {
  // Create a new useForm instance from react-hook-form to handle our form's state
  const {
    register,
    handleSubmit,
    reset,
    formState: { errors },
  } = useForm<PromptFormInputs>({
    // Pass the form's values using our Zod schema to ensure the inputs pass validation
    resolver: zodResolver(promptFormSchema),
    defaultValues: {
      prompt: "",
    },
  });

  return (
    <div className="flex flex-col gap-1 w-full items-center max-w-xl">
      <form
        className="flex w-full space-x-2"
        onSubmit={handleSubmit((data) => {
          // Run the onSubmitHandler passed into the component and then reset the form after submission
          onSubmitHandler(data);
          reset();
        })}
      >
        <Input
          type="text"
          placeholder="What would you like to ask?"
          disabled={isGenerating}
          {...register("prompt", { required: true })}
        />
        <Button type="submit" disabled={isGenerating}>
          Submit
        </Button>
      </form>
      {errors.prompt?.message && (
        <p className="text-sm text-red-600 self-start">
          {errors.prompt?.message}
        </p>
      )}
    </div>
  );
}

A fair amount is going on in this file so let’s take a moment to break it down and see what’s going on. The first thing we do in the form is create a new instance of useForm from react-hook-form which is the package we’re going to be using for handling our form’s state. We pair this with a custom Zod schema that will parse the inputs to the form and will handle all of our validation and error-generating for us.

We then define the UI itself by creating a new form element and passing in the onSubmitHandler that is passed in as a prop to the component. Then we define our form’s UI which is just a single input and button before rendering any errors out to the page that has been thrown by react-hook-form and Zod.

Home Wrapper

With our GenericPromptInput taken care of, let’s now write the HomePromptInput component which will wrap it and provide the custom onSubmitHandler for it. To create this function, add a new file in the prompt-inputs directory we created previously called home.tsx and add the below code to it.

"use client";

import { createConversation } from "@/app/actions/db/create-conversation";
import { GenericPromptInput } from "./generic";
import { PromptFormInputs } from "@/types";
import { useRouter } from "next/navigation";

export function HomePromptInput() {
  const router = useRouter();

  // onSubmit hanlder to create a new conversation in the DB based on the user's prompt and then redirect to that conversation's page using the UUID
  const onSubmitHandler = async (data: PromptFormInputs) => {
    const { uuid } = await createConversation(data.prompt);

    router.push(`/${uuid}`);
  };

  return <GenericPromptInput onSubmitHandler={onSubmitHandler} />;
}

You can see in comparison this file is much simpler, and all we have in the file is the custom onSubmitHandler function which is where we run the logic for creating the new conversation in the database using the Server Action we defined at the top of this section.

Then after the conversation is created in the database, we take the uuid returned to us and redirect the user to it, this is then where the logic for the individual conversation page will take over and trigger the AI to generate a response to the prompt the user inputted, we’ll write this logic and functionality in the next section when we look at building the individual conversation page.

Now, with the form input complete for the home page, the last thing we need to do is to update the home page’s UI to display the form as well as some other generic text to inform the user what to do. We can do this by updating the page ./app/page.tsx with the below code.

import { HomePromptInput } from "@/components/prompt-inputs/home";

export default function Home() {
  return (
    <main className="flex h-full flex-col items-center justify-between p-12">
      <div className="flex flex-col items-center gap-1 my-auto">
        <h1 className="font-bold text-2xl">What would you like to ask?</h1>
        <p>Ask me anything!</p>
      </div>
      <HomePromptInput />
    </main>
  );
}

Again, this is another simple block of code as the primary purpose of this page is to render the input for the user to interact with and then redirect the user to the conversation’s individual page where the majority of the functionality will happen so let’s take a look at building that next. But, as a final recap, your application should now look something like this.

Conversation Page

At this point, we have nearly built the entirety of the application, the last piece of functionality that we need to implement is also the most important, the individual conversation page. On this page, users will be able to read the entire conversation history they’ve had as well as prompt the AI to generate more responses off the back of that conversation. So, let’s start implementing it!

Custom Context

The first thing we need to look at implementing for our conversation page is a custom context provider which will wrap the entire page and facilitate easy sharing of state across all of the components that will be rendered on this page.

To create this context, create a new directory in the root of the project called context and then create a new file inside called conversation-context.tsx and add the below code to it.

// This code was based on an article from Kent C. Dodds (https://kentcdodds.com/blog/how-to-use-react-context-effectively)

import { conversationSchema } from "@/schema";
import {
  Dispatch,
  ReactNode,
  SetStateAction,
  createContext,
  useContext,
  useState,
} from "react";
import { z } from "zod";

const ConversationContext = createContext<
  | {
      conversation: z.infer<typeof conversationSchema> | undefined;
      setConversation: Dispatch<
        SetStateAction<z.infer<typeof conversationSchema> | undefined>
      >;
      isGenerating: boolean;
      setIsGenerating: Dispatch<SetStateAction<boolean>>;
    }
  | undefined
>(undefined);

function ConversationProvider({ children }: { children: ReactNode }) {
  const [conversation, setConversation] = useState<
    z.infer<typeof conversationSchema> | undefined
  >(undefined);
  const [isGenerating, setIsGenerating] = useState(false);

  const value = {
    conversation,
    setConversation,
    isGenerating,
    setIsGenerating,
  };

  return (
    <ConversationContext.Provider value={value}>
      {children}
    </ConversationContext.Provider>
  );
}

function useConversation() {
  const context = useContext(ConversationContext);

  if (context === undefined) {
    throw new Error(
      "useConversation must be used within a ConversationProvider"
    );
  }

  return context;
}

export { ConversationProvider, useConversation };

In this code, we do a few things, we create a new provider which we can use to wrap our page and then we also define a new custom hook called useConversation that will allow us to access the data inside the context.

Inside the context, we have four values, the state container the current conversation’s data and a way to update that state as well as if the AI is currently generating a response or not and a way to update that state.

Finally, if you would like to learn more about this way of writing context in React, I highly recommend checking out this Kent C. Dodds post that this code was based on.

Implementing the Functionality

With our custom context now created, we’re ready to start work on creating the final pieces of functionality for our application. In total we’re going to need to create three new Server Actions and three new components as well so let’s get started.

Conversation Prompt Input

Let’s start by taking a look at some code we’re already familiar with and that’s building the conversation page wrapper of the prompt input component we made in the last section for our home page. As you may recall, I mentioned earlier that the conversation page and the home page will actually share the same input component but with different onSubmitHandler functions so let’s go about creating the conversation page’s version now.

However, before we can write the component itself, we first need to create a couple of new Server Actions (getOneConversation and updateConversation) that we’ll then use in the onSubmitHandler in the component. We can create these Server Actions by creating two new files in our app/actions/db directory from earlier, get-one-conversation.ts and update-conversation.ts. Then, once you have these new files add the respective code below.

"use server";

import { db } from "@/config";
import { conversationSchema } from "@/schema";
import { GetCommand } from "@aws-sdk/lib-dynamodb";
import { currentUser } from "@clerk/nextjs";

export const getOneConversation = async (uuid: string) => {
  const currentUserData = await currentUser();

  try {
    // Fetch the provided conversation UUID for the user from the DB
    const { Item } = await db.send(
      new GetCommand({
        TableName: process.env.DB_TABLE_NAME,
        Key: {
          pk: `USER#${currentUserData?.id}`,
          sk: `CONVERSATION#${uuid}`,
        },
      })
    );

    // Return the data to the frontend, passing it through Zod
    return conversationSchema.parse(Item);
  } catch (error) {
    console.log(error);
    throw new Error("Failed to fetch conversation");
  }
};

"use server";

import { db } from "@/config";
import { UpdateCommand } from "@aws-sdk/lib-dynamodb";
import { currentUser } from "@clerk/nextjs";
import { getOneConversation } from "./get-one-conversation";
import { conversationSchema } from "@/schema";

export const updateConversation = async (uuid: string, prompt: string) => {
  const currentUserData = await currentUser();

  if (!currentUserData) {
    throw new Error("User not found");
  }

  // Fetch the current conversation from the DB
  const { conversation } = await getOneConversation(uuid);

  try {
    // Update the target conversation with the new prompt from the user's form submission
    const { Attributes } = await db.send(
      new UpdateCommand({
        TableName: process.env.DB_TABLE_NAME,
        Key: {
          pk: `USER#${currentUserData?.id}`,
          sk: `CONVERSATION#${uuid}`,
        },
        UpdateExpression: "set conversation = :c",
        ExpressionAttributeValues: {
          ":c": [
            ...conversation,
            {
              author: `USER#${currentUserData?.id}`,
              content: prompt,
            },
          ],
        },
        ReturnValues: "ALL_NEW",
      })
    );

    // Return the new conversation with the updated messages to the frontend
    return conversationSchema.parse(Attributes);
  } catch (error) {
    console.error(error);
    throw new Error("Failed to update conversation");
  }
};

With these two new Server Actions added, we can now turn our attention to the UI aspect of the component. To create this UI add a new file in the ./components/prompt-inputs directory called conversation.tsx and add the code below.

"use client";

import { updateConversation } from "@/app/actions/db/update-conversation";
import { GenericPromptInput } from "./generic";
import { PromptFormInputs } from "@/types";
import { useConversation } from "@/context/conversation-context";

interface IProps {
  uuid: string;
}

export function ConversationPromptInput({ uuid }: IProps) {
  const { setConversation, isGenerating } = useConversation();

  // onSubmit handler to update the conversation in the DB with the user's new prompt and update the data in context
  const onSubmitHandler = async (data: PromptFormInputs) => {
    const updatedConversation = await updateConversation(uuid, data.prompt);

    setConversation(updatedConversation);
  };

  return (
    <GenericPromptInput
      onSubmitHandler={onSubmitHandler}
      isGenerating={isGenerating}
    />
  );
}

In this code, you can see we have a fairly basic onSubmitHandler which is similar to the one we wrote earlier for the home page but this time we’re updating the conversation instead of creating a new one. The other notable difference is that instead of us redirecting the user to another page we’re instead updating the current conversation stored in the context we created earlier with the updated data following the user’s form submission.

Conversation Display

At this point, we’ve now finished all of the forms for our project and the user is now able to submit new conversations as well as update existing ones with new prompts so now let’s turn our attention to displaying the conversation messages and triggering responses from the AI to make this chatbot come alive!

To do this we’re going to need to create the final Server Action in our project which is the one that is going to communicate with AWS Bedrock to generate new AI responses based on our inputs. To create this, create a new directory in our ./app/actions directory called bedrock and then add a new file inside it called generate-response.ts with the below code.

"use server";

import { bedrock, db } from "@/config";
import { getOneConversation } from "../db/get-one-conversation";
import { InvokeModelCommand } from "@aws-sdk/client-bedrock-runtime";
import { bedrockResponseSchema, conversationSchema } from "@/schema";
import { UpdateCommand } from "@aws-sdk/lib-dynamodb";
import { currentUser } from "@clerk/nextjs";

export const generateResponse = async (uuid: string) => {
  const currentUserData = await currentUser();
  const { conversation } = await getOneConversation(uuid);

  // Build the prompt for the AI using the correct syntax
  const prompt = conversation
    .map(({ author, content }) => {
      if (author === "ai") {
        return `${content}`;
      } else {
        // Wrap any user inputs in [INST] blocks
        return `[INST]${content}[/INST]`;
      }
    })
    .join("");

  // Prepare the input for the AI model
  const input = {
    accept: "application/json",
    contentType: "application/json",
    modelId: "meta.llama2-70b-chat-v1",
    body: JSON.stringify({
      prompt,
      max_gen_len: 512,
      temperature: 0.5,
      top_p: 0.9,
    }),
  };

  let generation = "";

  try {
    // Invoke the Bedrock AI model with the prepared input
    const bedrockResponse = await bedrock.send(new InvokeModelCommand(input));

    // Parse the response from Bedrock to get the generated text
    const response = bedrockResponseSchema.parse(
      JSON.parse(new TextDecoder().decode(bedrockResponse.body))
    );

    generation = response.generation;
  } catch (error) {
    console.error(error);
    throw new Error("Failed to generate response from Bedrock");
  }

  try {
    // Update the conversation in the database adding the updated response to the end of the conversation
    const { Attributes } = await db.send(
      new UpdateCommand({
        TableName: process.env.DB_TABLE_NAME,
        Key: {
          pk: `USER#${currentUserData?.id}`,
          sk: `CONVERSATION#${uuid}`,
        },
        UpdateExpression: "set conversation = :c",
        ExpressionAttributeValues: {
          ":c": [
            ...conversation,
            {
              author: "ai",
              content: generation,
            },
          ],
        },
        ReturnValues: "ALL_NEW",
      })
    );

    // Return the updated conversation to the frontend
    return conversationSchema.parse(Attributes);
  } catch (error) {
    console.log(error);
    throw new Error("Failed to update conversation");
  }
};

A fair amount is happening in this Server Action so let’s take a moment to dive into it and see what’s going on. The first thing we do is fetch the current conversation data from the database based on the uuid of the conversation that’s provided, we do this using our getOneConversation Server Action from earlier.

We then take this data and convert the existing messages inside it into the correct structure that the AI model is expecting which includes wrapping any user messages in [INST] blocks. After this, we then prepare the input object for our Bedrock request which includes defining the model ID we want to use as well as any parameters we want to use to customize the AI’s response as well as finally including the body we prepared with our messages in.

We then send our request to AWS Bedrock and wait for a response. Once we have the response, we parse it to get the generated reply and then update the conversation in the database to have the latest AI response added to the end. Finally, we then return the updated conversation to the front end so it can be displayed to the user.

With our Server Action now implemented, all we need to do is build the matching frontend UI that will invoke this Server Action and display all of the messages to the user. To do this, create a new component in the ./components directory called conversation-display.tsx and add the below code to it.

"use client";

import { generateResponse } from "@/app/actions/bedrock/generate-response";
import { getOneConversation } from "@/app/actions/db/get-one-conversation";
import { useConversation } from "@/context/conversation-context";
import { useEffect } from "react";
import { MdOutlineComputer, MdOutlinePersonOutline } from "react-icons/md";

interface IProps {
  uuid: string;
}

export function ConversationDisplay({ uuid }: IProps) {
  const { conversation, setConversation, isGenerating, setIsGenerating } =
    useConversation();

  // When the page loads for the first time, fetch the conversation for the page UUID from the DB and add it to the context
  useEffect(() => {
    async function fetchConversation() {
      const conversation = await getOneConversation(uuid);
      setConversation(conversation);
    }

    fetchConversation();
  }, []);

  // When the conversation is updated run this useEffect
  useEffect(() => {
    async function generateAIResponse() {
      if (isGenerating) return;

      setIsGenerating(true);

      const lastAuthor = conversation?.conversation.at(-1)?.author;

      /**
       * If the lastAuthor is the 'ai' then we know the user needs to respond so return early and update the context state
       * If the conversation is falsy, also return and and update the context state
       */
      if (!conversation || lastAuthor === "ai") {
        setIsGenerating(false);
        return;
      }

      // Generate a new reply from the AI and update the conversation in the context state below.
      const generatedReponse = await generateResponse(uuid);

      setConversation(generatedReponse);
      setIsGenerating(false);
    }

    generateAIResponse();
  }, [conversation]);

  return (
    <div className="flex flex-col items-start gap-12">
      {conversation?.conversation.map((message, ind) => (
        <div
          className="flex flex-row gap-4 items-start"
          key={`${message.content}-${ind}`}
        >
          {message.author === conversation.pk ? (
            <div className="bg-violet-400 rounded-sm p-2 text-white">
              <MdOutlinePersonOutline size={20} />
            </div>
          ) : (
            <div className="bg-green-400 rounded-sm p-2 text-white">
              <MdOutlineComputer />
            </div>
          )}
          <p key={message.content}>{message.content}</p>
        </div>
      ))}
    </div>
  );
}

In this component, we request the current conversation from the database when the page first renders, we then store this data in our context. After the conversation data is stored in context it triggers our second useEffect block which is where the request to generate the AI response happens.

In this second useEffect block we perform a series of checks to see if an AI response is required or not. For example, we check if the last response was from the AI or the user and if a generation request is already in progress. If a request to the AI is required, we then submit the request using the Server Action we wrote a moment ago before setting the updated conversation data returned to us from the Server Action to our context which would then trigger a re-render and the new message to appear.

While we’re talking about the second useEffect block it’s also worth mentioning that this block will also be triggered when a user submits a new message in the conversation because the onSubmitHandler we defined before updates the conversation stored in the context which will trigger this useEffect block to rerun.

Finally, we then render out all of the messages stored in our context for that conversation by mapping over them and displaying their content as well as an icon to indicate if they came from the AI or the user.

Generating Banner

Finally, with our conversation messages now displaying, we have one last piece of UI we need to create before we can tie it all together. This final piece of UI is a simple component that will display “Generating” on the screen to inform the user that a request to the AI is in progress. This component will also prevent the user from submitting new messages while a request is happening, helping to prevent duplicate requests to the AI.

To create this component, create a new file in the components directory called generating-banner.tsx and add the below code to it.

"use client";

import { useConversation } from "@/context/conversation-context";
import { AiOutlineLoading } from "react-icons/ai";

export function GeneratingBanner() {
  const { isGenerating } = useConversation();

  return (
    <div
      className={`fixed top-1/2 left-1/2 transform -translate-x-1/2 -translate-y-1/2 w-full h-full flex flex-col items-center justify-center gap-4 bg-gray-100/75 ${
        isGenerating ? "opacity-100" : "opacity-0 -z-10"
      }`}
    >
      <AiOutlineLoading className="animate-spin text-gray-700" size={56} />
      <p className="text-2xl font-semibold animate-pulse">Generating...</p>
    </div>
  );
}

In this component, we use our useConversation hook to retrieve the current value of the isGenerating state. We then use this value to conditionally style the banner so that it animates onto the page when a request to Bedrock is in progress before hiding again when the request finishes.

Tying it All Together

To finish off the conversation page and tie all of the UI and functionality we’ve created together, let’s create our new conversation page by creating a new directory in the app directory called [uuid] and then adding a new file to that directory called page.tsx with the below code.

"use client";

import { ConversationPromptInput } from "@/components/prompt-inputs/conversation";
import { ConversationDisplay } from "@/components/conversation-display";
import { GeneratingBanner } from "@/components/generating-banner";
import { ConversationProvider } from "@/context/conversation-context";

interface IPageProps {
  params: {
    uuid: string;
  };
}

export default function Page({ params: { uuid } }: IPageProps) {
  return (
    <main className="relative flex h-full flex-row w-full items-center justify-center p-12 pb-0">
      <div className="h-full w-full max-w-3xl flex flex-col justify-between items-start gap-12">
        <ConversationProvider>
          <GeneratingBanner />
          <ConversationDisplay uuid={uuid} />
          <div className="w-full flex justify-center pb-12">
            <ConversationPromptInput uuid={uuid} />
          </div>
        </ConversationProvider>
      </div>
    </main>
  );
}

Similar to our home page this page is pretty simple and acts as a holding place for all of the other components we’ve defined in this section. But, there are some important things to note such as the uuid parameter we bring in as a prop which will control the active conversation we’re looking at. Another important thing is the ConversationProvider we have wrapping all of the components we’ve created to allow them access to the custom context we created.

Testing The Application

Now with all of the code added and all of the functionality implemented, we’re ready to give our new application a shot and test out its AI-generating abilities. To do this, start up your local dev instance if you haven’t already by running npm run dev and then head over to http://localhost:3000 in your browser.

Then once on your application if you don’t have an active session you should be redirected to the sign-in/up page we created. If you do have an account already you can now sign in and be taken to the home page otherwise sign up for a new one using the sign-up page.

Once you’re on the home page you can submit a new prompt using the input field and you should then be taken to the individual page for that conversation where after a second or two the AI should reply to your query. At this point, if you wish you can then submit another prompt and continue the conversation. Finally, if at any point you want to create a new conversation, you can use the + icon on the top of the sidebar to create a new standalone conversation via the home page.

At this point if all of the above worked as expected and you have an application that resembles the one shown in the video below then congrats you’ve completed the tutorial and have built your own ChatGPT-inspired chat application, called Chatrock!

Closing Thoughts

In this post, we’ve covered a lot of ground and we learned how to build a ChatGPT-inspired application called Chatrock that uses Next.js, AWS DynamoDB & Bedrock, and Clerk!

I hope you found this post helpful and if you have any questions at all or are stuck in any of the sections of this post, feel free to reach out to me and I’d be happy to help; all of the ways you can contact me are shown on my contact page.

Finally, if you would like to read the entire finished code, you can check out the GitHub repository here and if you would like to learn more about Clerk, make sure to read their excellent documentation here.

Thank you for reading.

NOTE: Once you’re finished with the application, if you want to remove the deployed DyanmoDB table, you can run the cdk destroy command from inside the infrastructure folder in the project. After accepting any prompts this will remove the database and all of the data inside it.

NOTE: This post was originally published on my blog - conermurphy.com/blog

Accurately Typing DynamoDB Data from the AWS SDK using TypeScript

Coner Murphy — Wed, 30 Aug 2023 07:22:26 +0000

This post was originally published on my blog on 10th August 2023

If you’ve ever tried building a project with DynamoDB and used the AWS SDK with TypeScript to read and write data to the database, you’ll probably be familiar with the issues of the SDK not typing the data you retrieve from the database.

This issue makes sense because the SDK has no way of knowing what attributes you have on every item in your database before you’ve retrieved them but this doesn’t make the issue any less annoying from a developer's perspective.

But, don’t worry in this tutorial, I’ll give you a solution so you can keep the power of the SDK and have accurate types from TypeScript for you to use in your application so let’s get into it.

The Issue

Before we jump into the solution let’s take a quick look at the problem, below is some example code using the QueryCommand from the AWS SDK to retrieve all items in the database that match the given pk and start with the same sk value.

const { Items } = await dbClient.send(
  new QueryCommand({
    TableName: 'YOUR_TABLE_NAME',
    ExpressionAttributeValues: {
      ':p': pk,
      ':s': sk,
    },
    KeyConditionExpression: 'pk = :p and begins_with(sk, :s)',
  })
);

The issue with this code is the TypeScript type given to Items will be Record<string, any>[] | undefined which is far from helpful. If we wanted to access the properties on the items returned from our database, TypeScript would throw an error as it has no idea what is present on the data and what isn’t so let’s fix that so we can access the actual data we retrieve with the correct types.

The Solution

To resolve the issue with the types not being applied to the data being returned, we first need to do some digging into the SDK package itself. If we dig into the QueryCommand we used above, we can actually see the return type being used is the one below.

export declare type QueryCommandOutput = Omit<__QueryCommandOutput, "Items" | "LastEvaluatedKey"> & {
    Items?: Record<string, NativeAttributeValue>[];
    LastEvaluatedKey?: Record<string, NativeAttributeValue>;
};

This is where we can see the not-very helpful Record<string, NativeAttributeValue>[] | undefined is being returned to us. But, what if we could override that with our own types?

What we’re going to do is take the QueryCommandOutput type and remove the built-in type for Items and instead give it our own type that matches the data we’re retrieving from the database. We can do this with the below code.

import { QueryCommandOutput } from '@aws-sdk/lib-dynamodb';

type Item = {
    prop1: string;
}

const { Items } = (await dbClient.send(
  new QueryCommand({
    TableName: 'YOUR_TABLE_NAME',
    ExpressionAttributeValues: {
      ':p': pk,
      ':s': sk,
    },
    KeyConditionExpression: 'pk = :p and begins_with(sk, :s)',
  })
)) as Omit<QueryCommandOutput, 'Items'> & {
    Items?: Item[];
  };

As mentioned above, we take the QueryCommandOutput type and use it with the Omit feature from TypeScript to remove the Items type. We then extend that type with our own type for Items which will be used for the Items property returned from the SDK.

So, in the case of our example above we took our Items property from having a type of Record<string, NativeAttributeValue>[] | undefined to having a type of Item[] | undefined which is a lot nicer to use and work with!

Making It Reusable With Generics

But, let’s not stop there, we can take this one step further and make our solution easier to reuse across our entire project by pairing it with generics and creating a new standalone type like the one below.

export type IQueryCommandOutput<T> = Omit<QueryCommandOutput, 'Items'> & {
  Items?: T;
};

We can now use this type with any QueryCommand in our codebase and provide it with a type to substitute with the generic T so we can have nicely typed data for all of our queries. Here is our example updated to use this new abstraction.

// types.ts

import { QueryCommandOutput } from '@aws-sdk/lib-dynamodb';

export type Item = {
    prop1: string;
}

export type IQueryCommandOutput<T> = Omit<QueryCommandOutput, 'Items'> & {
  Items?: T;
};

// query.ts

import { Item, IQueryCommandOutput } from './types';

const { Items } = (await dbClient.send(
  new QueryCommand({
    TableName: 'YOUR_TABLE_NAME',
    ExpressionAttributeValues: {
      ':p': pk,
      ':s': sk,
    },
    KeyConditionExpression: 'pk = :p and begins_with(sk, :s)',
  })
)) as IQueryCommandOutput<Item[]>;

Example Code Snippets

We’ve covered the QueryCommand from the AWS SDK throughout this post but here are the snippets you’ll need for the other common commands used when interacting with a DynamoDB table via the AWS SDK.

Scan

export type IScanCommandOutput<T> = Omit<ScanCommandOutput, 'Items'> & {
  Items?: T;
};

Query

export type IQueryCommandOutput<T> = Omit<QueryCommandOutput, 'Items'> & {
  Items?: T;
};

Get

export type IGetCommandOutput<T> = Omit<GetCommandOutput, 'Item'> & {
  Item?: T;
};

Put

export type IPutCommandOutput<T> = Omit<
  PutCommandOutput,
  'Attributes'
> & {
  Attributes?: T;
};

Delete

export type IDeleteCommandOutput<T> = Omit<
  DeleteCommandOutput,
  'Attributes'
> & {
  Attributes?: T;
};

Update

export type IUpdateCommandOutput<T> = Omit<
  UpdateCommandOutput,
  'Attributes'
> & {
  Attributes?: T;
};

Considerations

While this method does work great and all of the values returned to you from the SDK will have the appropriate types you passed to the generic, something you will need to bare in mind is that you’ll need to manually maintain the TypeScript types/interfaces you use.

This is because the types can’t be created from the database items themselves so we need to manually create the types and align them with the data in the database. This of course could introduce some issues if the types aren’t kept up to date or aren’t accurate to the data being stored.

However, I do think this issue is a minor one compared to the benefits of having working types assigned to the data returned from the SDK.

Closing Thoughts

We’ve now reached the end of this post; in this tutorial, we’ve looked at how to type the data returned to us from a DynamoDB table using the AWS SDK in a TypeScript project. I hope you found this post helpful until next time.

Thank you for reading

Coner

Handling Contact Forms Submissions With a Custom REST API using AWS SES, API Gateway, and Lambda

Coner Murphy — Thu, 10 Aug 2023 19:33:53 +0000

When it comes to building contact forms for a website, you could use a paid service to handle the sending of form submissions to you but in a world where everything is going subscription based do you really want to add one more to your list?

So, in this tutorial, we’ll be exploring how to build a REST API that can process requests and send the contents of those requests as an email to a designated email address. You would then be able to take the URL of this API and make requests to it from a frontend application and allow users to submit contact forms to then be delivered to your inbox. I’ll demonstrate this functionality by using Postman to send requests to our API.

For this project, we’ll be using the same email address to receive the submissions as well as to send them. So, in practice, we’re emailing ourselves the contents of the requests sent to our API but if you wanted to you could update this and use a different receiving email address to the sending one.

Also, for this tutorial, I’ll be using the AWS CDK but if you would rather complete this project using the AWS dashboard, then make sure to check out my past tutorial on this, it also includes a frontend project example for building a contact form.

The AWS services we’ll be using in this tutorial are:

API Gateway: For creating our REST API and API key for authentication
Lambda: For creating a function to handle the processing of requests and request the sending of emails via SES
SES: Sending the emails and configuring our email address to send the emails
IAM: To give permission to our Lambda function to allow sending emails using SES.

Now, we know what we’ll be building and what we’ll be building it with we’re almost ready to get started. But, before we get into the tutorial, I just want to mention that you’ll need to have an AWS account created as well as have the AWS CDK and CLI configured on your machine, along with having an existing CDK project. You can learn how to do all of this in under 60 seconds with my tutorial on TikTok here.

Configuring SES to Send Emails

The first thing we need to do in our CDK project is define the email address we want to send our form submissions from, this is called a verified email identity. To create this verified identity, add the below code to our stack definition file in the lib directory; make sure to update YOUR_EMAIL_ADDRESS to the email address you want to send emails from.

// 1. Define our SES Verified Email Address
const verifiedEmail = 'YOUR_EMAIL_ADDRESS';
const identity = Identity.email(verifiedEmail);
new EmailIdentity(this, 'SESIdentity', {
  identity,
});

Adding Our Lambda Processor Function

With SES now configured and ready to go, let’s shift our focus to the Lambda function we’ll be using to process requests from our API and then request the sending of emails with SES. The first thing we want to do is define our Lambda function in our stack definition file, so just below the SES code, add the code below for our Lambda function.

// 2. Create our Lambda functions to handle requests
const sendEmailLambda = new NodejsFunction(this, 'SendEmailLambda', {
  entry: 'resources/send-email.ts',
  handler: 'handler',
  environment: {
    VERIFIED_EMAIL: verifiedEmail,
  },
  initialPolicy: [
    new PolicyStatement({
      actions: ['ses:SendEmail'],
      resources: [
        `arn:aws:ses:${this.region}:${this.account}:identity/${identity.value}`,
      ],
    }),
  ],
});

The two important things to note with this definition are that we pass the email address we configured with SES to our Lambda function as an environment variable so we can access it inside the function. And, secondly, we add a new IAM policy to our Lambda to allow it to send emails using SES with the email address we configured.

With both of those things covered, let’s move on to creating the actual function that our Lambda will execute. To do this, create a new file at ./resources/send-email.ts and then inside it add the below code.

import { SESClient, SendEmailCommand } from '@aws-sdk/client-ses';
import { APIGatewayProxyEvent } from 'aws-lambda';

interface IEventBody {
  firstName: string;
  lastName: string;
  email: string;
  message: string;
}

const sesClient = new SESClient({});

export const handler = async (event: APIGatewayProxyEvent) => {
  // If no body, return an error
  if (!event.body) {
    return {
      statusCode: 400,
      body: JSON.stringify({ message: 'Missing body' }),
    };
  }

  const { VERIFIED_EMAIL = '' } = process.env;

  // Get data from the request sent from the frontend that triggered the lambda
  const body = JSON.parse(event.body) as IEventBody;
  const { firstName, lastName, email, message } = body;
  const requiredFields = ['firstName', 'lastName', 'email', 'message'];

  // Check all of the required fields are present in the body
  for (const key of requiredFields) {
    if (!body[key as keyof IEventBody]) {
      return {
        statusCode: 400,
        body: JSON.stringify({ message: `Missing field: ${key}` }),
      };
    }
  }

  // Config for SES to send the email
  const params = {
    // Email address the email is sent to
    Destination: {
      ToAddresses: [VERIFIED_EMAIL],
    },
    Message: {
      // Body of the email
      Body: {
        Text: {
          Data: `
New message:
---
Name:${firstName} ${lastName}
Email: ${email}
Message: ${message}
`,
        },
      },
      // Subject line of the email
      Subject: { Data: `Contact Form Message` },
    },
    // Email address the email is sent from
    Source: VERIFIED_EMAIL,
  };

  // Send the email
  try {
    const response = await sesClient.send(new SendEmailCommand(params));

    if (response.$metadata.httpStatusCode !== 200) {
      return {
        statusCode: 500,
        body: JSON.stringify({ message: 'Error sending email' }),
      };
    }

    return {
      statusCode: 200,
      body: JSON.stringify({ message: 'Email sent' }),
    };
  } catch (e) {
    return {
      statusCode: 500,
      body: JSON.stringify({ message: e }),
    };
  }
};

In this function, we take the body from the API request and check it contains all of the defined required fields before configuring the parameters required for SES to send our email and finally, sending the actual email.

Inside the lambda, we also do several checks to handle potential errors; for example, the request body not being provided, required fields being missed, or if an error happens with SES sending the email. Each of these will return an error code with a relevant message to our client sending the request.

Finally, at this point, it’s worth remembering that the email we send from and to is the same email address (the one we verified in SES). However, if you wanted, you could configure the receiving email address to be a different email address by changing the array passed to the ToAddresses property in the SES config. But it’s important we keep the Source property as the email address we verified in SES otherwise, the emails won’t send.

Creating an API to trigger our Lambda function

With our Lambda function now defined and written, we’re ready to move onto the final piece of our CDK stack and that’s defining our new REST API. To define our new REST API, add the below code under the Lambda definition we created earlier in the stack definition file in the lib directory.

// 3. Define our REST API
const api = new RestApi(this, 'EmailApi', {
  restApiName: 'EmailApi',
  defaultCorsPreflightOptions: {
    allowOrigins: Cors.ALL_ORIGINS,
    allowMethods: Cors.ALL_METHODS,
  },
  apiKeySourceType: ApiKeySourceType.HEADER,
});

// 4. Create our API Key
const apiKey = new ApiKey(this, 'EmailApiKey');

// 5. Create a usage plan and add the API key to it
const usagePlan = new UsagePlan(this, 'EmailUsagePlan', {
  name: 'Email Usage Plan',
  apiStages: [
    {
      api,
      stage: api.deploymentStage,
    },
  ],
});

usagePlan.addApiKey(apiKey);

// 6. Connect our Lambda functions to our API Gateway endpoints
const sendEmailIntegration = new LambdaIntegration(sendEmailLambda);

// 7. Define a POST handler on the root of our API
api.root.addMethod('POST', sendEmailIntegration, {
  apiKeyRequired: true,
});

In this code, we define several things, we start by defining our new REST API before then adding a new API key and a usage plan to connect our API and API key together. We then configure a new LambdaIntegration which is how we connect our API and Lambda function. Before, finally, defining the endpoint to which we want users to send their requests along with the Lambda function we want that endpoint to trigger.

In our case, we’ll be using the root of the API with a POST request which will trigger the Lambda function we created earlier for processing the results.

It’s worth mentioning that creating REST APIs with API Gateway and the AWS CDK can be a complicated subject so to help with this I’ve created a standalone tutorial that goes into a lot more depth than this tutorial, you can check it out here.

Deploying Our New API

We’ve now defined all of the services we need for our new REST API to process requests from a contact form and send the results to our target email address. But, before we can deploy our CDK stack to our AWS account, we need to add one more output to our CDK stack for our API key ID. So, at the bottom of your stack definition file in your lib directory add the below code.

// Misc: Outputs
new cdk.CfnOutput(this, 'API Key ID', {
  value: apiKey.keyId,
});

With that code added we’re ready to deploy our CDK stack, so in the terminal run the command cdk deploy and then accept any prompts you’re given. Once your deployment has finished, you should have two outputs in your terminal that look like the below.

SesSendEmailApiStack.APIKeyID = YOUR_API_KEY_ID
SesSendEmailApiStack.EmailApiEndpoint2C21ACE3 = YOUR_API_URL

Now, we have our API key ID we can get our actual API key by using the AWS CLI and running the command aws apigateway get-api-key --api-key <YOUR_API_KEY_ID> --include-value. Then once we have our API key value from the result shown to us in the terminal, we can perform requests to our API using a tool like Postman which is what we’ll be doing in the next section!

Testing Our New API With Postman

Before we can test our new API, we first need to complete the verification process for the email address we configured with SES at the start of the tutorial. To complete this process, check the inbox of the email address you configured for an email from AWS, inside that email should be a link, if you click that link it will complete the verification process and take you to a page confirming its completion.

With our email address now verified, we’re ready to configure Postman to test our new API. To do this, add our API URL to the URL input field in Postman and select the request method of POST as that’s what we configured our API to use.

We’ll then want to configure our API key to be included in the request by adding a header to the request. To do this, under the “Headers” tab in Postman, add a new entry with the key of x-api-key and the value as your API key.

Finally, we need to add a body to our request, to do this, go to the “Body” tab and select the “raw” option before then adding the below JSON (customize the values as you want).

{
    "firstName": "FIRST_NAME",
    "lastName": "LAST_NAME",
    "email": "EMAIL_ADDRESS",
    "message": "MESSAGE"
}

You can then hit the send button in Postman and within a few moments, you should receive an email in the inbox of the email address you specified at the start of this tutorial (or, if you changed it, the email address you added to the ToAddresses property instead). You should also receive a response in Postman with a status code of 200 and a body of {"message": "Email sent"}.

At this point we know our API works but if you would like to test your API further than a successful request, here are some more tests you could run to test some of the failure conditions we handled inside the function.

No API key provided: 403 Forbidden
API key and no request body provided: 400 - Missing body
API key and missing required fields: 400 - Missing field: MISSING_FIELD_NAME

Closing Thoughts

And, if all of the tests passed successfully then congrats you have a working API that you can use to send contact form messages to a target email address. All you need to do now is send requests to your API URL from your frontend with your API key and a body containing the required fields, the rest is handled for you!

So, I hope you found this tutorial on building a REST API to handle contact form submissions using the AWS CDK helpful and if you’d like to see the full example code for this project, you can see it over on my AWS CDK examples repository here.

And, until next time, thank you for reading.

Coner

This post was originally published on my blog on 30th July 2023
---

Reducing Latency: Pre-Warming Lambda Functions with EventBridge Rules

Coner Murphy — Thu, 03 Aug 2023 16:53:10 +0000

For any application, it’s important to have low latency times to ensure a fast and responsive experience for users. But, this is especially true for serverless applications; they need low latency times to ensure they’re responsive to requests, can easily scale to meet demand, and are able to remain cost-effective.

That’s why in this post we’re going to be taking a closer look at AWS Lambda and how cold-starts can cause increased latency and reduced performance as well as how we can mitigate these issues by keeping our lambda functions warm using EventBridge rules.

Cold and Warm Lambda’s

But, first, what are cold and warm lambdas? A cold lambda is a lambda that hasn’t been loaded into the execution environment, this is typically because it has either not been invoked before or hasn’t been invoked for a significant period. This means when we go to invoke a cold lambda, AWS needs to set up the resources and infrastructure required to execute the function and it’s this setup that causes an increase in latency and response time.

It’s also worth remembering that the setup time can vary from function to function for several reasons but two of the most consequential reasons are the size and complexity of a function. More complicated lambdas that use more resources will take longer to set up and can often have setup times of multiple seconds. This might not seem a long time but for applications that require near-instantaneous responses like APIs, a few seconds is unacceptable.

So, now, we know what a cold lambda is, what about a warm one? A warm lambda is a lambda function that is already present in the execution environment because it’s either been executed recently or it receives frequent invocations. This means when we invoke a warm function, AWS doesn’t need to set up any new resources or infrastructure because it’s already in place from a previous invocation, this means we get a (typically) much lower latency and faster response time.

At this point, you might be asking how can I keep my lambda’s warm then. To which I’ll respond, there are a few ways you can keep a lambda warm but the one we’ll be focusing on in this tutorial is a technique called pre-warming. This is where we use recurring requests to invoke our lambda function to keep it in the execution environment and therefore warm. We’ll perform the pre-warming by using an EventBridge rule on a cron job that is set to trigger our function every 5 minutes.

How to Keep a Lambda Warm

Now, we’re up to date with the theory behind warm lambda functions and why we might want to use them; let’s take a look at how we can implement them into a CDK project as well as the latency savings they give us.

So, inside a CDK project, we’re going to define two lambdas, one to be our cold lambda and one to be our warm one. You can define these lambdas using the below code.

// 1. Defining our Warm and Cold Lambda Functions
const warmLambda = new NodejsFunction(this, "WarmLambda", {
  runtime: Runtime.NODEJS_16_X,
  entry: "./resources/warm-lambda.ts",
  handler: "handler",
  timeout: Duration.seconds(30),
});

const coldLambda = new NodejsFunction(this, "ColdLambda", {
  runtime: Runtime.NODEJS_16_X,
  entry: "./resources/cold-lambda.ts",
  handler: "handler",
  timeout: Duration.seconds(30),
});

After defining our functions, we’re then going to define the EventBridge rule that will trigger our warm lambda function every 5 minutes with the below code.

// 2. Defining our CloudWatch Event Rule for our CRON job to run every 5 minutes
const rule = new Rule(this, "Rule", {
  schedule: Schedule.cron({
    minute: "*/5",
  }),
});

// 3. Defining our warm Lambda function as the target for our CloudWatch Event Rule, also pass through an event for us to use in the function to exit early
rule.addTarget(
  new LambdaFunction(warmLambda, {
    event: RuleTargetInput.fromObject({
      source: "aws.events",
    }),
  })
);

In this code we also pass through an event object to our warm lambda function, this is important because we’ll use this object to determine if the lambda was triggered by us or the EventBridge rule.

If the lambda was triggered by the EventBridge rule, we’ll return early from the function so the lambda is executing for as little time as possible to help reduce costs as we’re billed for the total execution time.

With our lambda functions and EventBridge rule defined, let’s finish off our example project by writing the code for our lambda functions. For this, create a new directory in the root of your project called resources and then inside it, create two files cold-lambda.ts and warm-lambda.ts, and then add the corresponding code below to them.

import { EventBridgeEvent } from "aws-lambda";

export const handler = (
  event: EventBridgeEvent<
    string,
    {
      source: string;
    }
  >
) => {
  // If triggered by the cron job, return early from the function
  if (event.source === "aws.events") {
    return;
  }

  console.log("Hi! I am a warm Lambda function.");
};

export const handler = () => {
  console.log("Hi! I am a cold Lambda function.");
};

Testing Our Lambdas

With the code for our lambda functions added, we’ve finished all we need for our cold/warm lambda example so let’s deploy it by running cdk deploy. Then after our deployment has finished, let’s wait for 5/10 minutes for our warm lambda to be triggered a couple of times to be 100% sure it’s warm and loaded into the execution environment.

So, after we’ve waited for our warm lambda to warm up, let’s invoke both lambdas by using the AWS CLI and running the command aws lambda invoke --function-name <LAMBDA_NAME> --invocation-type Event - for both of our lambda functions, making sure to switch <LAMBDA_NAME> for the name of the lambda function.

Once you’ve invoked both of the lambda’s, let’s check out their latency times by heading over to CloudWatch in the AWS dashboard. Click into both of the lambda function’s logs, and you should find logs similar to those below but with different IDs.

Warm Lambda

c9509a8b-1534-4a1a-aee4-cfb94138c5aa INFO Hi! I am a warm Lambda function.
REPORT RequestId: c9509a8b-1534-4a1a-aee4-cfb94138c5aa Duration: 1.50 ms Billed Duration: 2 ms Memory Size: 128 MB Max Memory Used: 58 MB

Cold Lambda

7c0c7027-f70a-4f45-aa16-28c84d33f801 INFO Hi! I am a cold Lambda function.
REPORT RequestId: 7c0c7027-f70a-4f45-aa16-28c84d33f801 Duration: 16.80 ms Billed Duration: 17 ms Memory Size: 128 MB Max Memory Used: 57 MB Init Duration: 154.67 ms

The bit of these logs we’re interested in is the “Duration:” property on the bottom line, this gives us the total time the lambda was executing; including the startup time to prepare the environment for the lambda to execute.

For the cold lambda, we have a total duration of 16.80ms, and for the warm lambda, a total duration of 1.50ms. This means by pre-warming our environment we’ve achieved a reduction of 15.30ms or ~90% which might not seem a lot but considering the simplicity of the lambda functions we’re running that’s a massive time saving which will only get bigger as the time and complexity of our lambda’s increase.

Considerations

So, now we’ve seen the potential of pre-warming our lambda’s, let’s take a moment to consider some of the considerations we might want to think about when deciding whether or not we want to implement pre-warming into our projects.

Cost

It’s worth considering if keeping your lambda’s warm is a necessity for your project. This is because while the lower latencies are nice, there will be an increase in cost to account for the extra lambda invocations and execution time being used. Whether or not pre-warming your lambdas is worth the cost will likely depend on your project type. For example, for an API it would make sense as the low latency is a priority but for an automated data scraping function, it probably won’t make sense.

Reliability/Inconsistency

While pre-warming our lambda functions with EventBridge rules will work most of the time, there is the chance that your lambda’s will go cold between invocations. This means some of your requests will have higher latencies while the execution environment is configured again.

So, if the possibility of this inconsistency isn’t acceptable for your project, you might want to look into something like Provisioned Concurrency. This will guarantee several warm lambdas are always ready to use but this will also incur extra costs compared to the pre-warming technique.

Monitoring/Adjustments

Because pre-warming is a technique for keeping lambda’s warm, not a guarantee they will keep warm. You will need to spend some time monitoring and adjusting your EventBridge rules to ensure they work optimally for your project.

This is because if the cron period is too long, your functions may go cold and require a cold start with higher latencies. But, if they’re too short, you might be executing Lambda’s unnecessarily, increasing your costs.

Closing Thoughts

We’ve now reached the end of the post so to recap; we’ve looked at what are cold and warm lambda’s as well as why we might want to keep our lambda’s warm. We then looked into how we can use EventBridge rules on a cron job to keep a lambda warm and the latency improvements of doing so. Before finally, concluding the post by looking at some of the considerations we should think about when deciding if pre-warming lambda’s are right for our project or not.

I hope you found this post helpful and if you’d like to see the example project I used for this tutorial, you can see it on my GitHub repository along with all of the other tutorial projects I’ve done.

Thank you for reading

Coner

How to Build a REST API With the AWS CDK Using API Gateway, Lambda, and Dynamodb With API Key Authentication

Coner Murphy — Wed, 05 Jul 2023 18:56:33 +0000

APIs are a common occurrence in the developer world and for a good reason, they allow us to easily connect separate systems and products together. It’s highly likely that at some point in your developer journey, you’ll use one but today we’re going to go one step further and look at how we can create one with AWS using API Gateway, Lambda, DynamoDB, and the AWS CDK.

But, first, why might you want to create one? There are many reasons why you might want to create an API but one of the most common would be to give external developers an easy way to integrate with your product or platform to perform operations as if they were using the product directly.

So, by the end of this post, we’re going to have created an example REST API that allows users to create, delete, and retrieve example blog posts from a DynamoDB table. We’re also going to protect our API by requiring an API key to be used in the requests so any unauthenticated requests are responded to with a 403 Forbidden response.

Prerequisites

Before we jump into the tutorial and get started with building our example API, there are a couple of things to take care of. You’ll need to have an AWS account, as well as the AWS CLI and CDK, configured on your local machine. You will also need a CDK project initialized locally, this can either be an existing one you’d like to add an API to or a brand new one.

Finally, you’ll need a way of testing the API we build. You could opt for something like curl but I’d recommend using Postman as it provides a nice UI for testing APIs and their responses.

With that all covered and out of the way, let’s get started with building our AWS API.

DynamoDB

The first thing we need to do in our CDK Stack is define our new DynamoDB table which we’ll use to store the post data created via our API. To define your new table, add the below code into the class in your stack definition file in the lib directory.

// 1. Create our DynamoDB table
const dbTable = new Table(this, 'DbTable', {
  partitionKey: { name: 'pk', type: AttributeType.STRING },
  removalPolicy: RemovalPolicy.DESTROY,
  billingMode: BillingMode.PAY_PER_REQUEST,
});

With this code, we create a new DynamoDB table that uses a partiionKey of pk and is set to use on-demand mode as well as to be removed when we destroy the stack so we don’t leave any lingering data.

API Gateway

With our DynamoDB table taken care of; let’s move on to step 2 and create our new REST API in API Gateway. To do this add the code below under the code we just added for our DB table.

const api = new RestApi(this, 'RestAPI', {
  restApiName: 'RestAPI',
  defaultCorsPreflightOptions: {
    allowOrigins: Cors.ALL_ORIGINS,
    allowMethods: Cors.ALL_METHODS,
  },
  apiKeySourceType: ApiKeySourceType.HEADER,
});

With this code, we create our new REST API, give it a name in the AWS Dashboard, and configure our CORS options. We also configure where the API key will be stored for the requests to our API, which will be in the header of the requests.

Speaking of our API key, let’s create a new one, to do this add the below code under the code we just added to create our REST API.

// 3. Create our API Key
const apiKey = new ApiKey(this, 'ApiKey');

This code will generate a new API key to use with our API when we deploy our CDK stack to AWS.

It’s worth noting that in an actual deployment of an API if you wanted to allow users to generate their own API keys, you would use the AWS SDK and something like a Lambda function to generate the API key instead of doing it via the CDK. But, for our example project where we only need one API key this method will work fine.

Usage Plan

The final thing we need to configure for API Gateway at the moment is a usage plan. Usage plans are how we can implement things like throttling, quota limits, and monetization on an API. But, for this post, we’re not going to be looking at those features, instead the thing we’re most interested in is the access control functionality that usage plans offer. Read more about API Gateway Usage Plans.

For API key authentication to work, we need to associate the API key we just generated with a usage plan. If we don’t associate the API key with a usage plan then the API key won’t work and we’ll be unable to access our API with it.

But, before we can associate our API key with a usage plan, we first need to create our usage plan in our CDK stack. To do that add the below code under the API key code.

// 4. Create a usage plan and add the API key to it
const usagePlan = new UsagePlan(this, 'UsagePlan', {
  name: 'Usage Plan',
  apiStages: [
    {
      api,
      stage: api.deploymentStage,
    },
  ],
});

This code creates a new usage plan for the API we specify in the apiStages property. You’ll also notice the stage property in the configuration options, this is if you want to configure different usage plans for different stages of your API like “staging”, “production”, etc.

In this example, we’re just using the default stage of our API which is production so we don’t need to configure anything else here.

Finally, we just need to link our API key to our new usage plan which we can achieve by adding the below code under the code we just added for the usage plan.

usagePlan.addApiKey(apiKey);

Lambda

With the base of our new API configured, we’re now ready to move on to defining our Lambda functions and handlers which will contain the actual logic used when a user sends a request to our API. Let’s start by defining the Lambda functions in our CDK stack before then writing them and linking them to our API.

Defining our Lambda functions

Because our API is going to have 2 endpoints /posts and /posts/{id}, we’re going to have two Lambda functions, one for each of the endpoints.

To define these Lambda functions in our CDK stack, add the below code under the usage plan code we just added.

// 5. Create our Lambda functions to handle requests
const postsLambda = new NodejsFunction(this, 'PostsLambda', {
  entry: 'resources/endpoints/posts.ts',
  handler: 'handler',
  environment: {
    TABLE_NAME: dbTable.tableName,
  },
});

const postLambda = new NodejsFunction(this, 'PostLambda', {
  entry: 'resources/endpoints/post.ts',
  handler: 'handler',
  environment: {
    TABLE_NAME: dbTable.tableName,
  },
});

With this code, we define two Lambda functions using the NodejsFunction construct and pass both of them the DynamoDB table name that we created earlier so we can access the table from within the function.

Granting read/write permissions

After defining the Lambda functions, the final thing we need to do is to grant them the necessary permissions to be able to read and write to our DynamoDB table which we can achieve with the below code.

// 6. Grant our Lambda functions access to our DynamoDB table
dbTable.grantReadWriteData(postsLambda);
dbTable.grantReadWriteData(postLambda);

Creating our handlers

Now our Lambda functions are defined and they have the necessary permissions to run, we just need to create them so let’s do that now.

To do this, we’ll need to create a series of new files and directories that will contain the code for the Lambda functions themselves as well as a series of handler functions that the Lambdas will use to access the DB and perform the required operations.

The final file structure should look like the one below.

// Existing directories in the root directory of the project  👇

- /lib
- /bin
- ...

// Files/Directories we've added 👇

- /resources
    - /endpoints (These are the Lambda functions)
        - post.ts (lambda for /posts/{id})
        - posts.ts (lambda for /posts)
    - /handlers
        - /posts (These are the handlers called from the Lambda functions)
            - create.ts
            - get-all.ts
            - get-one.ts
            - delete.ts

So, after creating the required files and folders, you should now have a resources directory at the root of your project alongside your lib and bin directories. And, then inside that resources directory you should have all of the files required for our Lambda functions to run.

Before we can populate these files with the required code however there are a couple of things we need to do.

We need to install some AWS NPM packages to allow us to access and operate on the DB table and have the required TS types. You can do this by running the command npm i @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb @types/aws-lambda aws-lambda.
We also need to create a type for our post data to be used in the create handler function so we can type the data passed to us from the request. To do this, create a new file in the root of the project called types.ts and add the below code into it.

export interface IPost {
  title: string;
  description: string;
  author: string;
  publicationDate: string;
}

With both of those things taken care of, we’re now ready to populate the contents of the files we created above. Below are the complete code snippets for each file we created.

***************Endpoints***************

// ./resources/endpoints/post.ts

import { APIGatewayProxyEvent } from 'aws-lambda';
import { getOne } from '../handlers/posts/get-one';
import { deletePost } from '../handlers/posts/delete';

export const handler = async (event: APIGatewayProxyEvent) => {
  const id = event.pathParameters?.id;

  if (!id) {
    return {
      statusCode: 400,
      body: JSON.stringify({ message: 'Missing path parameter: id' }),
    };
  }

  try {
    // Handle different HTTP methods
    switch (event.httpMethod) {
      case 'GET':
        return await getOne({ id });
      case 'DELETE':
        return await deletePost({ id });
      default:
        return {
          statusCode: 400,
          body: JSON.stringify({ message: 'Invalid HTTP method' }),
        };
    }
  } catch (error) {
    // eslint-disable-next-line no-console
    console.log(error);

    return {
      statusCode: 500,
      body: JSON.stringify({ message: error }),
    };
  }
};

The above code will be for our /posts/{id} endpoint so we take the id parameter out of the event that triggered the Lambda function. We then check if the id parameter is present or not and return a 400 error to the user if required. We then pass the id parameter into the relevant handler function depending on the HTTP method that was used in the request.

// ./resources/endpoints/posts.ts

import { APIGatewayProxyEvent } from 'aws-lambda';
import { getAll } from '../handlers/posts/get-all';
import { create } from '../handlers/posts/create';

export const handler = async (event: APIGatewayProxyEvent) => {
  try {
    // Handle different HTTP methods
    switch (event.httpMethod) {
      case 'GET':
        return await getAll();
      case 'POST':
        return await create(event.body);
      default:
        return {
          statusCode: 400,
          body: JSON.stringify({ message: 'Invalid HTTP method' }),
        };
    }
  } catch (error) {
    // eslint-disable-next-line no-console
    console.log(error);

    return {
      statusCode: 500,
      body: JSON.stringify({ message: error }),
    };
  }
};

The above function is for our /posts endpoint so we just trigger the relevant handler function depending on the HTTP method that was used. In the case of the create handler, we also pass through the body of the request to the API.

Handlers

// ./resources/handlers/posts/create.ts

import { DynamoDB } from '@aws-sdk/client-dynamodb';
import { PutCommand } from '@aws-sdk/lib-dynamodb';
import { randomUUID } from 'crypto';
import { IPost } from '../../../types';

const dynamodb = new DynamoDB({});

export async function create(body: string | null) {
  const uuid = randomUUID();

  // If no body, return an error
  if (!body) {
    return {
      statusCode: 400,
      body: JSON.stringify({ message: 'Missing body' }),
    };
  }

  // Parse the body
  const bodyParsed = JSON.parse(body) as IPost;

  // Creat the post
  await dynamodb.send(
    new PutCommand({
      TableName: process.env.TABLE_NAME,
      Item: {
        pk: `POST#${uuid}`,
        ...bodyParsed,
      },
    })
  );

  return {
    statusCode: 200,
    body: JSON.stringify({ message: 'Post created' }),
  };
}

With this function, we handle the creation of a new post in the database. We first check if the body is present and if it isn’t we return an error to the user to inform them. We then parse the body if it was provided, typing it as the IPost we created earlier before then performing the PutCommand with the SDK to add the item to the database.

// ./resources/handlers/posts/delete.ts

import { DynamoDB } from '@aws-sdk/client-dynamodb';
import { DeleteCommand } from '@aws-sdk/lib-dynamodb';

const dynamodb = new DynamoDB({});

export async function deletePost({ id }: { id: string }) {
  await dynamodb.send(
    new DeleteCommand({
      TableName: process.env.TABLE_NAME,
      Key: {
        pk: `POST#${id}`,
      },
    })
  );

  return {
    statusCode: 200,
    body: JSON.stringify({ message: 'Post deleted' }),
  };
}

This function handles the deletion of an existing post. We take in the id parameter from the request and then perform the DeleteCommand request in the SDK to delete the target item in the database.

// ./resources/handlers/posts/get-all.ts

import { DynamoDB } from '@aws-sdk/client-dynamodb';
import { ScanCommand } from '@aws-sdk/lib-dynamodb';

const dynamodb = new DynamoDB({});

export async function getAll() {
  const result = await dynamodb.send(
    new ScanCommand({
      TableName: process.env.TABLE_NAME,
    })
  );

  return {
    statusCode: 200,
    body: JSON.stringify(result.Items),
  };
}

In this function, we fetch all of the existing records in the database using the ScanCommand to read the entire database before returning them to the user.

// ./resources/handlers/posts/get-one.ts

import { DynamoDB } from '@aws-sdk/client-dynamodb';
import { GetCommand } from '@aws-sdk/lib-dynamodb';

const dynamodb = new DynamoDB({});

export async function getOne({ id }: { id: string }) {
  // Get the post from DynamoDB
  const result = await dynamodb.send(
    new GetCommand({
      TableName: process.env.TABLE_NAME,
      Key: {
        pk: `POST#${id}`,
      },
    })
  );

  // If the post is not found, return a 404
  if (!result.Item) {
    return {
      statusCode: 404,
      body: JSON.stringify({ message: 'Post not found' }),
    };
  }

  // Otherwise, return the post
  return {
    statusCode: 200,
    body: JSON.stringify(result.Item),
  };
}

Finally, with this function, we take the id parameter from the request and retrieve the post from the DB that matches it. If no item matches the provided id then we return a 404 error to the user to inform them.

Linking together our API and Lambda functions

With all of our Lambda functions and handlers now defined and written, we’re ready to link them to our API from earlier so that when a user sends a request to the API the relevant Lambda function and handler are triggered.

Creating the endpoints

The first thing we need to do when linking our API and Lambda functions together is to create the routes on our API for users to request. As you’ll recall from earlier we’re going to have 2 endpoints /posts and /posts/{id}. To define these on our API we can add the below code under the other code from earlier in the stack file in our lib directory.

// 7. Define our API Gateway endpoints
const posts = api.root.addResource('posts');
const post = posts.addResource('{id}');

What this code will create is a new /posts endpoint on the root of our API and then a new child endpoint on the /posts endpoint with the value {id}. It’s important to note the {} surrounding id as this is what denotes it will be a variable the user can pass in for us to retrieve as a parameter in the function.

Creating our Lambda integrations

After we’ve created the endpoints on our API, we need to create Lambda integrations out of our Lambda functions to connect to those endpoints. You can do this by adding the below code.

// 8. Connect our Lambda functions to our API Gateway endpoints
const postsIntegration = new LambdaIntegration(postsLambda);
const postIntegration = new LambdaIntegration(postLambda);

Creating our methods

Now, with our API endpoints, Lambda handlers, and Lambda integrations created and defined, we’re ready to link them all together by defining the methods that can be used on each endpoint. We can do this with the code below.

// 9. Define our API Gateway methods
posts.addMethod('GET', postsIntegration, {
  apiKeyRequired: true,
});
posts.addMethod('POST', postsIntegration, {
  apiKeyRequired: true,
});

post.addMethod('GET', postIntegration, {
  apiKeyRequired: true,
});
post.addMethod('DELETE', postIntegration, {
  apiKeyRequired: true,
});

Let’s break down one of these methods to better understand what is happening. We first choose the endpoint we’d like to add the method to (posts or post). We then call addMethod and pass in the HTTP method (GET, POST, DELETE) we’d like to add to that endpoint.

Before then passing the name of the Lambda integration we’d like invoked when that endpoint is requested with the specified HTTP method. Finally, we pass in the apiKeyRequired property to the options object to enforce the use of an API key with that method.

What this means is we have 2 API endpoints which both accept 2 HTTP methods and look a bit like the diagram below.

- /posts
    - GET
    - POST
    - /{id}
        - GET
        - DELETE

Outputs

With the above methods configured, we’ve finished defining our Rest API using API Gateway, Lambda, and DynamoDB via the AWS CDK.

But, before we can deploy it we need to add a final output statement to the CDK stack to print out our API key ID to the console so we can fetch its value with the AWS CLI to allow us to test the API with a tool like Postman.

To add this into your CDK stack add the below to the bottom of the stack file in the lib directory, just under where we defined our API methods a moment ago.

// Misc: Outputs
new CfnOutput(this, 'API Key ID', {
  value: apiKey.keyId,
});

Deploying our CDK stack

Before we can deploy our CDK stack to our AWS account, we need to ensure we have the esbuild package installed to allow the NodejsFunction construct to deploy successfully. So if you don’t already have esbuild installed, you can install it by using the command npm i -D esbuild.

After you have esbuild installed, you can deploy your CDK stack by running the command cdk deploy.

Testing your REST API

Once your CDK stack has finished deploying you should have two outputs in your terminal, one for the API key ID which we configured a moment ago, and another for the REST API URL.

The first thing we need to do before testing our API is to look up our API key value using the AWS CLI which we can do by using the command aws apigateway get-api-key --api-key API_KEY_ID --include-value. Make sure to switch out API_KEY_ID for the ID outputted from the CDK deploy command.

Once you’ve got your API key value, you’re ready to test your new REST API using a tool like Postman. To test an endpoint using Postman, you’ll want to enter the URL of your API followed by the endpoint you want to test. So for example our /posts endpoint would be API_URL/posts. You can then choose the HTTP method you want to use and add your API key value to the headers of the request with the key set to x-api-key and the value as your API key value.

While I won’t cover every test scenario you could perform against the API, here are some high-level tests you could run to make sure your API functions as intended.

Endpoint	Test	Expected Response
ALL	No API Key provided	403 Forbidden
GET: /posts	Returns list of posts	200 → Array of posts
POST: /post	Creates a new post with valid body	200 → “Post Created”
POST: /post	Missing body	400 → “Missing Body”
GET: /posts/{id}	Retrieves the target post ID	200 → Target posts data
DELETE: /posts/{id}	Deletes the target post ID	200 → “Post Deleted”

When it comes to performing the test to create a new post, you’ll need to pass in the data you want to create the post with to the body of the request. When testing this with Postman, you can use the raw option for the body and use the below JSON object for the body’s data.

{
    "title": "Example post 1",
    "description": "",
    "author": "me",
    "publicationDate": "some-date"
}

Closing Thoughts

If all of your tests have given the expected response then congratulations you have built and deployed a working REST API using API Gateway, Lambda, DynamoDB, and the AWS CDK as well as tested it using Postman!

Overall, even though there are a lot of steps involved in building a REST API with the AWS CDK when broken down into its individual steps it can be quite logical and straightforward to do. So, I hope you found this post helpful and if so I would be grateful if you would share it with others so they can find it helpful too.

If you would like to see the full example code for this project, you can see it on GitHub here.

And, until next time.

Thank you for reading

Coner

NOTE: Once you’re finished with this CDK project, make sure to remove it from your AWS account to ensure you don’t get billed for it by running cdk destroy.*

How to Build a Contact Form With Next.js and AWS

Coner Murphy — Mon, 06 Feb 2023 17:53:07 +0000

It’s pretty common nowadays to have a contact form on your website to make it a super simple process for people to contact you. And, while the functionality is quite simple in nature, actually building a contact form solution can be pretty involved depending on how little or how much you want to hand off to 3rd party packages and products.

However, not everyone wants to use 3rd party packages or solutions, whether that be because you want to learn something new or you want to fully control the process and code end to end. So, if you fall into the camp of wanting to control the process or are just curious about building with AWS, then this post is for you.

By the end of this post, we’re going to have a fully working contact form in Next.js that can send us emails quickly and cheaply using various AWS services.

Our Tech Stack

Before jumping into the tutorial, let’s cover the tech stack we’ll be using for this tutorial. Of course, as mentioned, we’ll be using Next.js and more specifically we’ll be making good use of the API routes feature. From an AWS perspective, we’ll be using a few services, which are SES, Lambda, API Gateway, and IAM.

📣 NOTE: For this tutorial, I’m going to be using the AWS Web UI to configure the various services listed but if you’re interested in seeing a version of this post using the AWS CDK make sure to let me know.

Configuring AWS

We’re going to start by configuring AWS, to get started, head over to AWS and sign in with your account if you already have one you want to use for this tutorial. Otherwise, create a new account.

As a quick note, if you’re going to create a new account for this tutorial, then make sure you create a new IAM user first before continuing with this tutorial as it’s bad practice to use the root user for provisioning new resources as detailed here.

After your account is ready to go and is all configured, choose the region you’re going to be deploying your resources to in the top right. For me, this will be eu-west-2 as that’s my closest region available.

SES

We’ll be configuring SES first, this is the service that will handle the sending of emails from our contact form to our specified email address. So, to get started, head over to SES by typing it into the search box in the top left of the AWS dashboard and clicking on “Amazon Simple Email Service”. Once, on the SES dashboard, click on “verified identities” on the left-hand sidebar and then click on “Create new identity” to add a new email address.

Then, click on “email address” and finally enter the email address you want the emails to be sent to and then click on “Create Identity”. You’ll now be sent an email to the email address that you need to open and click on a link to verify you own/have access to the email address. Once the email is verified, you’ll be able to send email to it using SES.

IAM

Our next stop is IAM so using the search box again, head over to the IAM dashboard and click on “Policies” on the left sidebar followed by “Create Policy”, switch to the JSON editor, and paste in the below JSON object.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "ses:SendEmail",
                "ses:SendRawEmail"
            ],
            "Resource": "*"
        }
    ]
}

With that JSON pasted in, push the new “next” button twice, and then on the “review” page name your new policy SendContactEmailPolicy and click on “Create Policy” to finish creating it.

Now, let’s use our new policy in a role that will allow a Lambda function to send emails using SES. To get started creating this role, go to “Roles” on the left sidebar, followed by “Create Role” and then choose “AWS Service” and “Lambda” from the options provided. Then click on “Next” and then on the “Permissions” screen, choose the policy we just created before finally clicking “next” again and then naming the new role SendContactEmail and clicking on “Create Role”.

That’s it, we’re now finished with IAM and have created the role our Lambda function will use in a moment to be allowed to access SES to send emails for us. Let’s move on to configuring Lambda next.

Lambda

Much like we did for SES and IAM, enter Lambda in your search box and click on its name to go to the Lambda dashboard. From there click on “Create function”, then “Author from scratch” and give it a name, I’ll be calling mine sendContactEmail, then finish creating your new function by clicking on “Create function”, leaving all the defaults in place.

Then open up your new Lambda function from the dashboard if it’s not already open and then select your index.mjs file in the code editor and paste into it the below code. You’ll need to make some changes in the code before we can deploy it though, these are.

Replace YOUR_VERIFIED_EMAIL with the email address you configured in SES earlier.
Replace AWS_REGION with the region you selected at the start.

With these changes made, you’re ready to deploy so press the “Deploy” button to save and make your Lambda ready to use.

const aws = require("aws-sdk");
const ses = new aws.SES({ region: "AWS_REGION" });

exports.handler = async function (event) {

    // Get data from the request sent from the frontend that triggered the lambda
  const { firstName, lastName, email, message } = JSON.parse(event.body);

  // Config for SES to send the email
  const params = {
        // Email address the email is sent to
    Destination: {
      ToAddresses: ["YOUR_VERIFIED_EMAIL"],
    },
    Message: {
            // Body of the email
      Body: {
        Text: { 
            Data: `
New message:
---
Name:${firstName} ${lastName}
Email: ${email}
Message: ${message}
` 
        },
      },
            // Subject line of the email
      Subject: { Data: `Contact Form Message` },
    },
        // Email address the email is sent from
    Source: "YOUR_VERIFIED_EMAIL",
  };

  // Send the email
  return ses.sendEmail(params).promise()
};

With our Lambda code configured and ready to go, we just need to configure a trigger for it using API Gateway. We can do a lot of this on our Lambda’s configuration page so to get started, select the “configuration” tab and then the “Triggers” sub-menu, then click on “Add Trigger”, then select “API Gateway” from the dropdown and click on “Create a new API”, followed by “REST API” and set the security equal to “API Key”. Then finish adding the new trigger by clicking “Add”.

Also, while we’re configuring the Lambda, let’s add in our IAM role from earlier to give it permission to send emails using SES. To do this, click on “Permissions” on the left-hand side of the “Configuration” page, then edit the “Execution Role” and select the role you created earlier from the “Use an existing role” dropdown. (You may need to hit the refresh button next to the dropdown if no items show up at first). Then press “save” to confirm those changes.

To finish off our Lambda/API Gateway configuration we need to obtain our REST API endpoint and API Keys to use with it for authentication. To do this, click on “Triggers” again and then copy your “API Endpoint”, keep this value safe as we’ll need it in a moment when we get into Next.js. Then under “Triggers” still, click on the name of your API to open the API Gateway dashboard, from their click on “API Keys” on the left, and then click on the name of the API Key based on your Lambda name from earlier. Finally, click on the “Show” option on the API key and copy this value as well.

And, that’s it! All of the AWS work is now complete and we’re ready to move into the frontend portion of this tutorial to hook up the contact form and get it working!

Configuring Next.js

If you have an existing Next.js repository you’d like to use with this tutorial you can but I’ll be creating a new one using npx create-next-app@latest --ts. Once you’ve created the project, cd into it and open the project in your favorite code editor. Throughout the frontend, I’ll be using TailwindCSS for styling, if you wish to use this as well, you can follow their great install guide. Otherwise, feel free to switch out the TailwindCSS styles for something else.

📣 NOTE: I’ll be using TypeScript in the Next.js project, if you’re not using TypeScript, you’ll need to edit the code to remove the TypeScript code and convert it to standard JavaScript.

The first thing we need to create is a .env.local at the root of the repository if it does not already exist. Then, inside this file, we need to add our endpoint and API Key from earlier like so.

CONTACT_FORM_ENDPOINT="YOUR_API_ENDPOINT_HERE"
CONTACT_FORM_API_KEY="YOUR_API_KEY_HERE"

If you’re using TypeScript, you may also wish to add an additional.d.ts file in the root of your project with the following contents.

declare global {
  namespace NodeJS {
    interface ProcessEnv {
      CONTACT_FORM_ENDPOINT: string;
      CONTACT_FORM_API_KEY: string;
    }
  }
}

export {};

This file just ensures that TS knows that the envs we’ve added are of the string type so won’t cause any linting errors with any or unknown types being used. To finish this setup, we just need to edit our tsconfig.json file. Inside your tsconfig.json add "additional.d.ts" to the includes array so it looks like the below.

{
  "compilerOptions": {
    ...compiler settings
  },
  "include": [...other files, "additional.d.ts"],
  "exclude": [...files]
}

After, configuring our env files, let’s move on to configuring our API route that will handle the actual submission of the data to the API Gateway endpoint we configured. So, create a new file at ./pages/api/contactForm.ts and paste into it the below code. We will also need to install isomorphic-fetch to allow us to use fetch in a Node.js environment so install that using npm i isomorphic-fetch.

import 'isomorphic-fetch';
import type { NextApiRequest, NextApiResponse } from 'next';
import { ContactFormValues } from '../../types';

interface ExtendedNextApiRequest extends NextApiRequest {
  body: ContactFormValues;
}

interface ExtendedNextApiResponse extends NextApiResponse {
  message: string;
}

type TBodyFields = {
  [key: string]: string;
};

export default async function contactForm(
  req: ExtendedNextApiRequest,
  res: ExtendedNextApiResponse
) {
  const { body }: { body: TBodyFields } = req;

  // Checking we have data from the email input
  const requiredFields = ['email', 'firstName', 'lastName', 'message'];

  for (const field of requiredFields) {
    if (!body[field]) {
      res.status(400).json({
        message: `Oops! You are missing the ${field} field, please fill it in and retry.`,
      });
    }
  }

  // Setting vars for posting to API
  const endpoint = process.env.CONTACT_FORM_ENDPOINT;

  // posting to the API
  await fetch(endpoint, {
    method: 'post',
    body: JSON.stringify({
      firstName: body.firstName,
      lastName: body.lastName,
      email: body.email,
      message: body.message,
    }),
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': process.env.CONTACT_FORM_API_KEY,
      charset: 'utf-8',
    },
  });

  res.status(200).json({ message: 'Success! Thank you for message!' });
}

In this function, we take in the body of the request, ensure all the fields we’ve specified as required are populated and then we send a POST request off to the API Gateway Endpoint we created. We also do some basic error handling so that if any required fields are not populated, we return an error to the user to let them know.

At this point, if you’re using TS, you will have some type errors for the missing ContactFormValues so let’s sort those out by creating a types.ts file at the root of the project and adding in the below type to resolve our type issue in the API route.

export type ContactFormValues = {
  email: string;
  firstName: string;
  lastName: string;
  message: string;
};

Now, we need to create a couple of custom React hooks to support the ContactForm component we’re going to be creating in a moment. The first one of these is called useContactForm and will handle the submission of the form to the Next.js API route so create a new file at ./hooks/useContactForm.ts and paste in the below code.

import { SyntheticEvent, useState } from 'react';
import { server } from '../config';
import { ContactFormValues } from '../types';

interface IProps {
  values: ContactFormValues;
  resetValues: () => void;
}

type Output = {
  message: string;
};

export default function useContactForm({ values, resetValues }: IProps) {
  // Setting state to be returned depending on the outcome of the submission.
  const [loading, setLoading] = useState<boolean>(false);
  const [outputMessage, setOutputMessage] = useState<string | null>('');
  const [error, setError] = useState<boolean | null>();

  // destructuring out the values from values passed to this form.
  const { firstName, lastName, email, message } = values;

  async function submitContactForm(e: SyntheticEvent) {
    // Prevent default function of the form submit and set state to defaults for each new submit.
    e.preventDefault();

    // Set base state
    setLoading(true);
    setError(null);
    setOutputMessage(null);

    // gathering data to be submitted to the serverless function
    const body = {
      firstName,
      lastName,
      email,
      message,
    };

    const requiredFields = ['email', 'firstName', 'lastName', 'message'];

    // Checking required fields aren't empty.
    for (const field of requiredFields) {
      if (!field?.length) {
        setLoading(false);
        setError(true);
        setOutputMessage(
          `Oops! The field: ${field} is empty, please fill it in and retry.`
        );
        return;
      }
    }

    // Send the data to the serverless function on submit.
    const res = await fetch(`${server}/api/contactForm`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(body),
    });

    const responseText: string = await res.text();

    // Waiting for the output of the serverless function and storing into the serverlessBaseoutput var.
    const output = (await JSON.parse(responseText)) as Output;

    // check if successful or if was an error
    if (res.status >= 400 && res.status < 600) {
      // Oh no there was an error! Set to state to show user
      setLoading(false);
      setError(true);
      setOutputMessage(output.message);
    } else {
      // everyting worked successfully.
      setLoading(false);
      setOutputMessage(output.message);
      resetValues();
    }
  }

  return {
    error,
    loading,
    outputMessage,
    submitContactForm,
  };
}

There’s a fair amount going in on this custom hook but essentially it handles the submission of the form to the API route and then handles the response from the API route as well as error and loading states that we can use in the UI. It also validates the required fields as well.

The next custom hook we need to create is the useForm hook which will handle the storing and updating of values used in the form prior to its submission. This means when we submit the form, we can take the values stored in the state of this hook as the values for the request to the API. So, to create this hook, create a new file at ./hooks/useForm.ts and paste into it the below code.

import { useState } from 'react';
import { ContactFormValues} from '../types';

type UpdateProps = {
  target: {
    value: string;
    name: string;
  };
};

export type UseFormUpdateValues = ({
  target: { value, name },
}: UpdateProps) => void;

interface ReturnProps {
  values: ContactFormValues;
  updateValue: UseFormUpdateValues;
  resetValues: () => void;
}

export default function useForm(
  defaults: ContactFormValues
): ReturnProps {
  const [values, setValues] = useState(defaults);

  function updateValue({ target: { value, name } }: UpdateProps) {
    // Set the value by spreading in the existing values and chaging the key to the new value or adding it if not previously present.
    setValues({
      ...values,
      [name]: value,
    });
  }

  function resetValues() {
    setValues(defaults);
  }

  return { values, updateValue, resetValues };
}

Finally, we just need to create our ContactForm component to consume the custom hooks we’ve created above. So, add a new file at ./components/ContactForm.tsx with the below code.

import React from 'react';
import useContactForm from '../hooks/useContactForm';
import useForm from '../hooks/useForm';

export default function ContactForm(): JSX.Element {
  const { values, updateValue, resetValues } = useForm({
    firstName: '',
    lastName: '',
    email: '',
    message: '',
  });

  const { firstName, lastName, email, message } = values;

  const { loading, outputMessage, submitContactForm } = useContactForm({
    values,
    resetValues,
  });

  const inputContainerStyles =
    'flex flex-col items-start ';
  const labelStyles = 'font-bold mb-1 ';

  return (
    <div className="flex flex-col justify-start items-center p-6 rounded-md col-span-5 xl:col-span-2">
      <form
        onSubmit={submitContactForm}
        className="flex flex-col gap-4 md:gap-6 w-full"
        data-testid="contact-form"
      >
        <div className="grid grid-cols-1 sm:grid-cols-2 w-full gap-4">
          <div className={inputContainerStyles}>
            <label htmlFor="firstName" className={labelStyles}>
              First Name
            </label>
            <input
              type="text"
              name="firstName"
              id="firstName"
              required
              placeholder="Your first name"
              onChange={updateValue}
              value={firstName}
              className="rounded-md  text-md w-full"
            />
          </div>
          <div className={inputContainerStyles}>
            <label htmlFor="lastName" className={labelStyles}>
              Last Name
            </label>
            <input
              type="text"
              name="lastName"
              id="lastName"
              required
              placeholder="Your last name"
              onChange={updateValue}
              value={lastName}
              className="rounded-md text-md w-full"
            />
          </div>
        </div>
        <div className={inputContainerStyles}>
          <label htmlFor="email" className={labelStyles}>
            Email Address
          </label>
          <input
            type="email"
            name="email"
            id="email"
            required
            placeholder="Your email"
            onChange={updateValue}
            value={email}
            className="rounded-md text-md w-full"
          />
        </div>
        <div className={`grow ${inputContainerStyles}`}>
          <label htmlFor="message" className={labelStyles}>
            Message
          </label>
          <textarea
            name="message"
            id="message"
            required
            placeholder="Your message"
            onChange={updateValue}
            value={message}
            className="rounded-md text-md w-full resize-none h-full max-h-[150px]"
          />
        </div>
        <button
          type="submit"
          className="bg-blue-600 text-white text-base font-bold rounded-md py-3 px-5"
        >
          {loading ? 'Sending..' : 'Send Message'}
        </button>
      </form>
      <p
        className={`text-md lg:text-base mt-6 ${
          !outputMessage ? 'animate-pulse' : ''
        }`}
      >
        {outputMessage || 'Awaiting Submission...'}
      </p>
    </div>
  );
}

And, that’s it, we’ve just created the contact form component and completed all of the work required for the frontend to send a request to the API in AWS to send us an email with the contents of the contact form. Let’s now test it by adding our contact form to our home page so in your ./pages/index.ts file, import your new ContactForm component and add it to the page. Then, start up your development server using npm run dev and fill in the contact form and press submit, if all went to plan, you should have an email drop in your inbox in a few moments with the details you just entered!

Closing Thoughts

If everything went to plan, you should now have a fully functional contact form using AWS and Next.js. So just to recap, in this post, we used the AWS web interface to configure multiple AWS services to work together with our Next.js frontend to handle the submission of a contact form and have it automatically sent to our configured email address.

If you’re interested in seeing the completed code for this project, you can see the Next.js code on my GitHub here.

And, as a closing note, if you followed along with this tutorial for a learning experience and don’t plan on actually using the services configured, make sure to go back through the tutorial and delete/de-provision everything that was configured in AWS so you don’t get any unexpected bill.

Finally, I hope you found this post interesting, enjoyable, and helpful and if you’re interested in working with me, I’d love to hear from you and how I can help you and/or your business.

Thank you for reading.

📣This post was originally published on my blog a week prior 📣

Creating Linked Blog Post Headers using MDX on GatsbyJS.

Coner Murphy — Thu, 27 May 2021 19:53:46 +0000

MDX is a great way to blog if you're a developer. I've been using it on my personal website for a few years now and have had very little reason to switch from it.

One of it's biggest pros is how flexible it is. If you want to add some new fields or change the way it displays, you can easily do it from your codebase.

Today, we're going to be looking at how to create linkable headers for every blog post on a GatsbyJS website using MDX.![

Prerequisites

Before starting this you need to have a blog already set up on GatsbyJS using MDX. If you have a GatsbyJS blog already but haven't converted it over to MDX, you can check out the MDX plugin page here.

If you already have all your blog posts generated using MDX then you're ready to get started.

Basic Setup

One of the reasons I love using GatsbyJS is because after defining one template file, all our blog posts are generated using it. This makes adding in linked headers a breeze because we only need to amend the template.

For this to work, we need to ensure our MDX is being generated using a list of custom components. To do this create a separate file with all the components that you need to use. Below is an excerpt from mine. If you want to view the whole file, you can on my GitHub repo here.

import styled from "styled-components";
import React from "react";

const H1 = styled.h1`
  font-size: 2.75rem;
`;

const Components = {
  h1: (props) => <H1>{props.children}</H1>,
};

For brevity, I've only included the H1 tag as an example. You will need to expand this out to all the header tags you want this to work for.

Once, we have this basic file laid out, we need to integrate it into our blog post template file like so:

import { MDXRenderer } from "gatsby-plugin-mdx";
import { MDXProvider } from "@mdx-js/react";
import Components from "../components/mdx/Components";

<MDXProvider components={Components}>
  <MDXRenderer>{body}</MDXRenderer>
</MDXProvider>;

By passing the components file to the MDXProvider it will use these components when rendering out the body of the post.

Adding the linked headers

Adding the functionality of the linked headers is as simple as amending the components file.

Here is an updated version with the functionality added.

import styled from "styled-components";
import React from "react";

const H1 = styled.h1`
  font-size: 2.75rem;
`;

function copyToClip() {
  navigator.clipboard.writeText(window.location);
}

const Components = {
  h1: (props) => (
    <H1 id={props.children.replace(" ", "-").toLowerCase()}>
      <a
        href={`#${props.children.replace(" ", "-").toLowerCase()}`}
        onClick={() => copyToClip()}
      >
        {props.children}
      </a>
    </H1>
  ),
};

Let's cover what's happening here.

When MDX renders the body, it passes each instance of each tag to the corresponding custom component. This allows us to retrieve the text by using props.children. We use this to create our URLs and IDs to link to.

For example, let's look at this section title:

Original header text: Adding the linked headers
URL/ID version: adding-the-linked-headers

By adding this text to the ID of the element we can link to it with an a tag.

Let's look at creating the link. First, we wrap the text of the element in an a tag with a href equal to the link we created earlier. Make sure to precede it with a # so we link to an id on the page and not an actual page.

So, with all the above sorted we have a H1 element on the page containing an a tag linking to the parent H1 tag.

As it stands this works. But, we're missing out on the best part. When someone clicks on the link we want it to copy to their clipboard so they can share it.

Clipboard Functionality

To add the clipboard functionality we need a onClick handler:

function copyToClip() {
  navigator.clipboard.writeText(window.location);
}

<a
  href={`#${props.children.replace(" ", "-").toLowerCase()}`}
  onClick={() => copyToClip()}
>
  {props.children}
</a>;

Now, when someone clicks on a header they have the URL copied to their clipboard.

Styling

All the functionality is now complete. The final thing we need to look at is the styling.

To show the user, that a link is clickable when they hover on it we want to underline the link and add a 🔗 emoji next to the link.

To achieve this, create a separate component like so:

const PostBodyContainer = styled.div`
  & > h1,
  h2,
  h3,
  h4,
  h5,
  h6 {
    position: relative;

    & > a {
      text-decoration: none;
      width: 100%;

      :hover {
        text-decoration: underline;

        & ::before {
          content: "🔗";
          transform: translateX(-2rem);
          position: absolute;
          font-size: 1.5rem;
          bottom: 12.5px;

          @media (max-width: 600px) {
            display: none;
          }
        }
      }
    }
  }
`;

We then wrap the MDX componets in this new component, like so:

<PostBodyContainer>
  <MDXProvider components={Components}>
    <MDXRenderer>{body}</MDXRenderer>
  </MDXProvider>
</PostBodyContainer>

Thanks to the ::before psuedo element we used, when someone hovers over the link they get the emoji appearing to the left of it and the link underlined.

Summing up

Following this tutorial, you should now have custom linkable headers set-up on a GatsbyJS blog using MDX. If you have any questions or any issues I would be happy to help. Just reach out to me over on Twitter and I'll get back to you as soon as possible.

If you found this post helpful, please consider sharing it so others can find it helpful to. If you want to see more content like this, please consider following me on Twitter where I regularly post threads and other posts.

Thanks for reading. 😃

How to Create a Custom Email Signup Form for ConvertKit on GatsbyJS.

Coner Murphy — Sat, 01 May 2021 00:00:00 +0000

Welcome back to my blog.

We all know the benefits that building a following online can bring. And, one of the most powerful tools for someone looking to build a following online is an email newsletter.

But, just having a newsletter isn't enough, we also need a way for people to sign up to it with minimal effort.

That's why in this post, I'm going to show you how I built a custom email newsletter signup form for ConvertKit on my GatsbyJS website. Let's do this.

There are 4 parts to building a custom subscriber form, these are:

The signup component users will interact with.
A custom hook to handle the form changes.
A custom hook to handle the submitting of the form.
A serverless function to actually submit the request.

Let's cover each one individually and see how the data flows between them.

The Signup Component

Because we are just building an email signup form the only inputs we need is a text input for the email and a submit button.

Here's a look at the code:

export const EmailSignup = () => {
  const { values, updateValue } = useForm({
    email: ''
  });
  const { message, loading, error, submitEmail } = useEmail({ values });
  const { email } = values;

  return (
    <>
      <FormGridContainer onSubmit={submitEmail}>
        <fieldset disabled={loading}>
          <label htmlFor="email">
            Email:
            <input
              type="email"
              name="email"
              id={`email-${Math.random().toString(36).substring(2, 15)}`}
              className="emailInput"
              onChange={updateValue}
              value={email}
            />
          </label>
        </fieldset>
        <button className="signupButton" type="submit" disabled={loading}>
          {loading ? 'Subscribing...' : ' Subscribe'}
        </button>
      </FormGridContainer>
      {message ? <OutcomeMessageContainer error={error} message={message} /> : ''}
    </>
  );
};

In the first part, we handle passing the data to and from the 2 helper functions that we will create: useForm and useEmail.

Then for the rest of the component, we handle displaying the data back to the user in the form and creating elements for them to interact with.

The only other part to note is at the bottom of the code. The component OutcomeMessageContainer is a styled-component that looks like this:

const OutcomeMessageContainer = ({ error, message }) => (
  <MessageContainer>
    {error ? <FaTimes data-error /> : <FaCheck />}
    <p>{message}</p>
  </MessageContainer>
);

As you can see we pass in 2 props, the error if there is one and the message returned back from the serverless function. we then display these to the user.

Now, let's look at the first helper function: useForm.

useForm

useForm is a small helper function to aid in the recording and displaying of information in the form.

It expands to include new values if required so all we need to do is pass in new defaults.

This is important because we want an easy way to access the data to pass to the next helper function useEmail.

Here's the code for useForm.

import { useState } from "react";

export default function useForm(defaults) {
  const [values, setValues] = useState(defaults);

  function updateValue(e) {
    // Get value from the changed field using the event.
    const { value } = e.target;

    // Set the value by spreading in the existing values and chaging the key to the new value or adding it if not previously present.
    setValues({
      ...values,
      [e.target.name]: value,
    });
  }

  return { values, updateValue };
}

Essentially, it boils down to a useState hook and a function to set the state.

The state it sets is an object containing the current values and any added ones.

For example, in our case the object set to the state would look like:

{
  email: "example@example.com";
}

If we then look back at our original component where we consume this hook you can see how we use it:

const { values, updateValue } = useForm({
  email: "",
});

const { email } = values;

First, we destructure out the values and the updateValue function that we returned. Then we destructure out the individual values beneath that.

When calling the hook we have to provide some default values for the hook to set to state.

We do this because otherwise when we access the email value on page load, it won't exist causing an error. To prevent this we create all the required state on load with a default value.

We then update this state as required.

Then on the input element in the form, we pass the updateValue function as the onChange handler like so:

<input
  type="email"
  name="email"
  id={`email-${Math.random().toString(36).substring(2, 15)}`}
  className="emailInput"
  onChange={updateValue}
  value={email}
/>

How does it know what index to update you may be asking?

Well, looking back at our useForm code, in the updateValue function:

function updateValue(e) {
  // Get value from the changed field using the event.
  const { value } = e.target;

  // Set the value by spreading in the existing values and chaging the key to the new value or adding it if not previously present.
  setValues({
    ...values,
    [e.target.name]: value,
  });
}

Here you can see that we destructure out the value we want to set to state from the event with e.target. Then when we set the state we get the name of the input from e.target again to be the key.

Looking at the above code, the name of the input element is email. This will update the state with the key email with the value from the target element.

To summarise:

We pass in a default state for email as an empty string.
Then use an onChange handler to update this state at a later date as the user begins to type in it.

useEmail

Let's take a look at the next helper function.

Here's the entire code which we will break down in a second:

import { useState } from "react";

export default function useEmail({ values }) {
  // Setting state to be returned depending on the outcome of the submission.
  const [loading, setLoading] = useState(false);
  const [message, setMessage] = useState("");
  const [error, setError] = useState();

  // destructuring out the values from values passed to this form.
  const { email } = values;

  const serverlessBase = process.env.GATSBY_SERVERLESS_BASE;

  async function submitEmail(e) {
    // Prevent default function of the form submit and set state to defaults for each new submit.
    e.preventDefault();
    setLoading(true);
    setError(null);
    setMessage(null);

    // gathering data to be submitted to the serverless function
    const body = {
      email,
    };

    // Checking there was an email entered.
    if (!email.length) {
      setLoading(false);
      setError(true);
      setMessage("Oops! There was no email entered");
      return;
    }

    // Send the data to the serverless function on submit.
    const res = await fetch(`${serverlessBase}/emailSignup`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
    });

    // Waiting for the output of the serverless function and storing into the serverlessBaseoutput var.
    const output = JSON.parse(await res.text());

    // check if successful or if was an error
    if (res.status >= 400 && res.status < 600) {
      // Oh no there was an error! Set to state to show user
      setLoading(false);
      setError(true);
      setMessage(output.message);
    } else {
      // everyting worked successfully.
      setLoading(false);
      setMessage(output.message);
    }
  }

  return {
    error,
    loading,
    message,
    submitEmail,
  };
}

It's a bit of a long one but it breaks down into logical chunks:

We create some state with default values, destructure values from the props and get the serverless base from our .env

export default function useEmail({ values }) {
  // Setting state to be returned depending on the outcome of the submission.
  const [loading, setLoading] = useState(false);
  const [message, setMessage] = useState("");
  const [error, setError] = useState();

  // destructuring out the values from values passed to this form.
  const { email } = values;

  const serverlessBase = process.env.GATSBY_SERVERLESS_BASE;

  // ... Rest of function
}

At this point the function hasn't been called, so we create the state accordingly:

loading -> false -> Not waiting on anything as not called
message -> "" -> No info returned so blank by default
error -> <EMPTY> -> No error has been generated as not called.

Then we destructure out the value we're interested in from the props email. This will be passed to the body of the submission request in a moment.

Then we get the serverless base from the .env file.

Learn more about Serverless Netlify Functions.

Defining the submitEmail function

Now, we're going to look at our submitEmail function, this is what will be called when the form is submitted. (We'll come back to this in a moment.)

async function submitEmail(e) {
  // Prevent default function of the form submit and set state to defaults for each new submit.
  e.preventDefault();
  setLoading(true);
  setError(null);
  setMessage(null);

  // gathering data to be submitted to the serverless function
  const body = {
    email,
  };

  // Checking there was an email entered.
  if (!email.length) {
    setLoading(false);
    setError(true);
    setMessage("Oops! There was no email entered");
    return;
  }

  // Send the data to the serverless function on submit.
  const res = await fetch(`${serverlessBase}/emailSignup`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

  // Waiting for the output of the serverless function and storing into the output var.
  const output = JSON.parse(await res.text());

  // check if successful or if was an error
  if (res.status >= 400 && res.status < 600) {
    // Oh no there was an error! Set to state to show user
    setLoading(false);
    setError(true);
    setMessage(output.message);
  } else {
    // everyting worked successfully.
    setLoading(false);
    setMessage(output.message);
  }
}

Once again, let's break this down into steps.

First we prevent the default behaviour of the form and update the state values we defined earlier on to show we're waiting on the request.

// Prevent default function of the form submit and set state to defaults for each new submit.
e.preventDefault();
setLoading(true);
setError(null);
setMessage(null);

We create the body of the request we're going to submit by using the values from earlier.

// gathering data to be submitted to the serverless function
const body = {
  email,
};

Before submitting the form, we check if the email length is greater than 0 or is truthy. If it isn't then we update the state to be an error, pass a custom error message and return the function.

// Checking there was an email entered.
if (!email.length) {
  setLoading(false);
  setError(true);
  setMessage("Oops! There was no email entered");
  return;
}

If the email value is truthy, then we progress with the submission and do a POST request to the serverless function with the body we created.

// Send the data to the serverless function on submit.
const res = await fetch(`${serverlessBase}/emailSignup`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
});

We await the reply from the serverless function, once received we convert it to text and parse it with JSON.parse.

// Waiting for the output of the serverless function and storing into the output var.
const output = JSON.parse(await res.text());

Then we get to the final part of the submit function. We check if the request was successful or not and set the state accordingly.

// check if successful or if was an error
if (res.status >= 400 && res.status < 600) {
  // Oh no there was an error! Set to state to show user
  setLoading(false);
  setError(true);
  setMessage(output.message);
} else {
  // everyting worked successfully.
  setLoading(false);
  setMessage(output.message);
}

Returning data

After we have processed the request, we return the below info back out of the helper function:

return {
  error,
  loading,
  message,
  submitEmail,
};

This gives us access to all the state we defined as well the submitEmail function we defined.

Using it in the Component

Back in the main component, we destructure out the values from the useEmail function like so:

const { message, loading, error, submitEmail } = useEmail({ values });

We consume the destructured values in the following places:

onSubmit function for the form

<FormGridContainer onSubmit={submitEmail}>

Disabling the submit button if loading is true and changing the text within it.

<button className="signupButton" type="submit" disabled={loading}>
  {loading ? "Subscribing..." : " Subscribe"}
</button>

We use the display component from earlier to show the message to the user and whether there has been an error or not.

{
  message ? <OutcomeMessageContainer error={error} message={message} /> : "";
}

Now we just need to look at the serverless function.

The Serverless Function

Let's now take a look at how we're going to use the information from useEmail in our serverless function to submit the request to ConvertKit.

But, before you can do this you'll need to get yourself an API key and create a form on ConvertKit. If you want to read more about their API, click here.

The API endpoint we will be making use of is:

https://api.convertkit.com/v3/forms/

Once you have your form id from the form you created and your API key we can get started.

Here is the full code:

require("isomorphic-fetch");

exports.handler = async (event) => {
  const body = JSON.parse(event.body);

  // Checking we have data from the email input
  const requiredFields = ["email"];

  for (const field of requiredFields) {
    if (!body[field]) {
      return {
        statusCode: 400,
        body: JSON.stringify({
          message: `Oops! You are missing the ${field} field, please fill it in and retry.`,
        }),
      };
    }
  }

  // Setting vars for posting to API
  const endpoint = "https://api.convertkit.com/v3/forms/";
  const APIKey = process.env.CONVERTKIT_PUBLIC_KEY;
  const formID = process.env.CONVERTKIT_SIGNUP_FORM;

  // posting to the Convertkit API
  await fetch(`${endpoint}${formID}/subscribe`, {
    method: "post",
    body: JSON.stringify({
      email: body.email,
      api_key: APIKey,
    }),
    headers: {
      "Content-Type": "application/json",
      charset: "utf-8",
    },
  });
  return {
    statusCode: 200,
    body: JSON.stringify({ message: "Success! Thank you for subscribing! 😃" }),
  };
};

Let's walk through this again as we did with the other functions:

Parse the JSON body that was sent from useEmail.

const body = JSON.parse(event.body);

Check we have filled the required fields, if not return an error saying they were missed.

// Checking we have data from the email input
const requiredFields = ["email"];

for (const field of requiredFields) {
  if (!body[field]) {
    return {
      statusCode: 400,
      body: JSON.stringify({
        message: `Oops! You are missing the ${field} field, please fill it in and retry.`,
      }),
    };
  }
}

Get our variables from .env and then submit a POST request to ConvertKit.

// Setting vars for posting to API
const endpoint = process.env.CONVERTKIT_ENDPOINT;
const APIKey = process.env.CONVERTKIT_PUBLIC_KEY;
const formID = process.env.CONVERTKIT_SIGNUP_FORM;

// posting to the Convertkit API
await fetch(`${endpoint}${formID}/subscribe`, {
  method: "post",
  body: JSON.stringify({
    email: body.email,
    api_key: APIKey,
  }),
  headers: {
    "Content-Type": "application/json",
    charset: "utf-8",
  },
});

Process the return

return {
  statusCode: 200,
  body: JSON.stringify({ message: "Success! Thank you for subscribing! 😃" }),
};

This is a smaller function because we did a lot of heavy lifting in the useEmail function.

As long as the required fields are populated we shouldn't have any issues with the request going through.

The Flow

To round up this post and tie together all of the steps we've gone through, let's look at the flow of data:

Email Form Component
👇
UseForm -> For storing form info
👇
Email Form Component
👇
useEmail -> onSubmit send the info to the serverless function
👇
Serverless Function -> Submit to ConverKit
👇
Email Form Component -> Display the success message

There's a fair amount going on between several files but the flow isn't too complicated. Obviously, if stuff goes wrong then the flow can be short-circuited.

The 2 main places for a short-circuit to happen would be useEmail and the serverless function.

Summing Up

I have been running a setup very similar to this on my website now for a few months and haven't had any issues. I like having all the functions separated into their own files as I do think it improves the readability.

The one thing we could add to improve this setup would be a Honeypot to capture any robots trying to fill in the form. But, I plan on covering this in a separate post where I can go more in-depth.

I didn't include any styling in this post for brevity, but if you're interested you can see it all on my GitHub here.

What do you think of this setup? Let me know over on Twitter.

I hope you found this post helpful. If you did please consider sharing it with others. If you would like to see more content like this please consider following me on Twitter.

Three Tools to Increase Your Productivity As a Developer.

Coner Murphy — Sat, 17 Apr 2021 00:00:00 +0000

Being productive is more than getting work done. Being productive is using our time to its greatest potential. By increasing our productivity we increase the return we get relative to the amount of effort we put in.

To ensure we stay on target and are always being as productive as possible we may need help. So, in this post, I've compiled three of my favourite apps to boost productivity.

Todoist

Todoist is a to-do list app that (in my opinion at least) is unmatched. I've tried countless methods of tracking my tasks and to-do lists but no app or method has come close to Todoist.

I tried pen and paper but found I never have it on me so I missed tasks; leading to reduced productivity.

I then tried moving my task lists to another one of my favourite apps, Notion. But, I found that while Notion is great for some things, being an everyday to-do list isn't one of them. As a whole, I found that Notion is too slow to be a task list.

Todoist doesn't suffer from these issues. It's always with me on my phone and it's quick so I can add tasks as soon as I think of them. Because Todoist is only focused on being a to-do list app, the UI/UX is designed for making task management a breeze.

I imagine I will be using Todoist for a long time. If you're interested in trying it out, you can check it out here.

Notion

While I said Notion isn't great for managing to-do lists, it's great for managing other things. If you need to track projects, content creation or anything that isn't a simple list then Notion has you covered.

I use Notion for tracking all my content and projects. If I come up with a blog post idea it's immediately added to Notion. Once it's in Notion, I use a Kanban board to progress all the posts through from concept to completion. I also repeat this for projects and other types of content.

Notion can be used for almost anything, part of its attractiveness is its flexibility. If you can dream it up, then you can likely make it in Notion. I won't cover all its features here but I recommend checking it out.

Forest

The final app on this list isn't a to-do list or a way of organising your projects and life.

Instead, it's a way to ensure you stay focused and on topic for a period of time. It forces you to be productive.

Forest is a great app that I've been using for years. It helps you use the Pomodoro technique. If you haven't heard it, it's a technique to be more productive by working in small sprints followed by rests. The standard period is 25 minutes of work followed by 5 minutes of rest. This is repeated 2/3 times before taking a longer period of rest such as 15 minutes.

Forest goes one step further though. It's not a timer like you would find on your phone. No, it actually locks you out of using your phone. If you try to open another app it will close the app you opened and return you to Forest until the timer finishes. Don't think you're slacking off anymore!

Also, if you sign up for the pro version they actually plant trees to help save forests! Check it out here.

How I use these apps

While it's great having these 3 apps on your phone/PC, that's not enough. What we need to do is optimise them and our use of them so we can maximise our productivity.

Here's a brief overview of how I use these apps in my workflow.

Every morning I go through my tasks on Todoist and check which ones have been completed. Then I add any tasks that are the next logical step.

For example, if I had a task to write a blog post, once I complete this, I would create a new task to edit it.

This isn't possible for all tasks as you may not know what's next. But whenever I can, I always make sure to add the next task. The less in my head the better because our minds make for bad filing cabinets.

As a rule of thumb, I won't use due dates unless they make sense. For example, if I had a task to take the car for a service, I'm unable to do it until the date of the service. In this case, the task will be dated for the service date. But, in the case of editing a post, it can be done whenever so I will add it with no due date and instead use a priority.

By using priorities it allows me to see all my tasks in one list in order of priority. Then I target the highest priorities first which should yield the greatest returns.

Once Todoist is updated, I set about updating and reviewing Notion.

As mentioned I use Notion for my projects and content, so it's pretty quick to update. First, I check all my content and projects are in the correct status. Then I check to see if I can add any more tasks to my Todoist because of status changes. So if a post is in the writing status, do I have a task to write the post? Or, if I've just finished it do I have a task to edit it?

It may seem like a lot of work managing the two apps. But, once you get set up and have a flow, you find that you check Notion once per day and run your life from Todoist instead.

Finally, I don't have a dedicated time I use Forest. Instead, it's something I use as and when a task requires my full attention. I don't use it for every task but for the tasks that require it, it's great.

Summing Up

These are the current apps I use in my endless pursuit of increased productivity. Now, I won't pretend that my system or these apps are the perfect solution for everyone. What's more important is the system you use, not the apps you use.

However, in the pursuit of increased productivity, we learn a lot about ourselves and how we like to work. What I recommend is building a system around this as it will yield the best productivity improvements.

What're your thoughts on these apps? What's your workflow? Let me know over on Twitter.

Thanks for reading.

This post was originally published on my blog: conermurphy.com. If you're interested in getting notified as soon as I publish a new post, please consider following me on Twitter.

How to Install Multiple NodeJS Versions Using NVM.

Coner Murphy — Mon, 12 Apr 2021 00:00:00 +0000

Recently, while I was updating my website I also wanted to upgrade the NodeJS version. Having explored this path in the past I knew it could be painful.

So on I went down the journey of upgrading NodeJS. I found there are multiple ways of tackling this problem. But, the best method I found is NVM or Node Version Manager.

In this post, we'll look at using NVM to install multiple NodeJS versions and how to switch between them at the drop of a hat.

Installing NVM

To install NVM it's as simple as running the authors install script which you can find here. You can either paste this into your terminal or you can run one of the below curl or wget commands to do it for you:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash

wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash

After running this script, you should notice the NVM repository has been copied into a ~/.nvm folder. Following this, the below code should now be added to your current terminal profile.

For example, I use ZSH for my terminal which is located in ~/.zshrc. After installing NVM I should find the below code copied into that file.

export NVM_DIR="$([-z "${XDG_CONFIG_HOME-}"] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[-s "$NVM_DIR/nvm.sh"] && \. "$NVM_DIR/nvm.sh" # This loads nvm

If everything went smoothly, NVM should now be installed!

Using NVM

Using NVM is simple, let's take a look at some of the most common commands you'll use:

Installing a New NodeJS Version

To install a new NodeJS version, you can use one of the below commands.

To get the latest version you can run:

nvm install node # "node" is an alias for the latest version

Or, if you have a particular version in mind:

nvm install 14.8.0 # or 10.10.0, 8.9.1, etc

NOTE: The first version you install becomes the default that new shell windows use.

Checking Installed NodeJS Versions

If you want to check what versions of Node you have installed you can run:

nvm ls

Checking What NodeJS Versions Can Be installed.

If you're interested in seeing what versions you can install using NVM, you can run:

nvm ls-remote

Switching NodeJS Versions

To switch between versions you can use:

nvm use 14.8.0 # or 10.10.0, 8.9.1, etc

Uninstalling Old NodeJS Versions

If you want to uninstall a version of Node you no longer need:

nvm uninstall 14.8.0 # or 10.10.0, 8.9.1, etc

Troubleshooting

If you were like me and run into the error nvm: command not found every time you try to run one of these commands. Or, you have another issue you can check out the troubleshooting section on the NVM GitHub Repo.

Unfortunately, my issue wasn't on the troubleshooting section so I had to do some digging. Here's how I solved it.

After retracing my steps, I found that the original install script hadn't added the below code to my ~/.zshrc.

export NVM_DIR="$([-z "${XDG_CONFIG_HOME-}"] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[-s "$NVM_DIR/nvm.sh"] && \. "$NVM_DIR/nvm.sh" # This loads nvm

After I opened my ~/.zshrc file and dropped in that code at the bottom, NVM started to work. If you're getting the nvm: command not found error try the troubleshooting guide first. If that doesn't help, check it was installed correctly.

If neither of these work I would recommend opening an issue on GitHub for some support.

Conclusion

That's it! NVM should now be installed and you should be able to install and use as many NodeJS versions as you please.

I hope you found this post helpful. If you did I would greatly appreciate you sharing it with others so they can find it helpful too. If you would like to see more content like this, please consider following me on Twitter.

Until next time, thank you for reading. 😃

This post was originally published on my blog: conermurphy.com. If you interested in finding out about my posts as soon as I release them please consider following me on Twitter.

How to Create Paginated Pages on GatsbyJS With Pagination Controls.

Coner Murphy — Sat, 10 Apr 2021 00:00:00 +0000

Welcome back to the blog! In this post, we are going to be looking at how to add pagination to pages on a GatsbyJS website. By the end of this post:

Your website will be able to create pages as required to house all your content.
The number of pages will be determined by the number of posts we want per page.
Finally, we will add controls to navigate between pages with the ability to skip to a certain page.

What Are We Creating?

Below is a screenshot from my live website conermurphy.com. Today, we will be covering the functionality that allows us to specify I want X posts per page and then have Gatsby create the pages for us. For the purposes of this tutorial, I will use a blog as an example, but this logic can apply to any page on a website. For example, I also use it with my notes on the website.

What we will finish with is the below URL structure:

yourURL.com/blog/ <- Posts 19-24
yourURL.com/blog/1 <- Posts 13-18
yourURL.com/blog/2 <- Posts 7-12
yourURL.com/blog/3 <- Posts 1-6

Check it out:

Prerequisites

So, what do you need to have done already before working through this tutorial?

As long as you have a working blog with some posts on it you will be good to go. For the purposes of this tutorial, I won't be covering how to set up sourcing content into Gatsby. Or, how to create the individual blog posts using a template file. But, if you are interested in these tutorials please let me know.

As long as you currently have a single page that has all your posts on it, you'll be good to go. 😃

If you are looking to set up your blog for the first time, LogRocket has a great tutorial here.

gatsby-node

Right, with all that out the way, let's get down to actually writing some code.

As mentioned above we should already have our posts sourced into Gatsby in the gatsby-node.js. Following this, they should display as one long list.

If your individual post page generation is already set up you should have a hook into the createPages API. If not that's okay, here's a quick overview.

createPages

createPages is an API of Gatsby Node that allows you to create pages dynamically. This API runs after the sourcing and transformation of nodes and the creation of the GraphQL schema is complete. Read more about it here.

In the following examples of code, I use ES6 Modules in my gatsby-node file, these aren't enabled by default. You can follow a tutorial I did on Twitter to set these up.

To start setting up the createPages API and the generation of the paginated pages, we need to add in the below code.

export async function createPages(params) {
  await Promise.all([turnBlogPostsIntoPages(params)]);
}

This allows us to hook into the createPages API. The Promise.all isn't necessary, you could add all the code into this one function. But, for readability, I separated out the individual generations into their own functions.

To illustrate this point, here is a direct copy from my current website:

export async function createPages(params) {
  // After the creation of the nodes create pages for each custom type.
  await Promise.all([
    // Blog Posts
    turnBlogPostsIntoPages(params),
    // Notes Pages
    turnNotesIntoPages(params),
    // Turn sourced Twitter Threads into pages.
    turnTwitterThreadsIntoPages(params),
    // Blog Tags Pages
    turnBlogPostTagsIntoPages(params),
    // Turn Notes Categories into pages
    turnNotesCategoriesIntoPages(params),
    // Turn Twitter Threads Tags Into Pages
    turnThreadsTagsIntoPages(params),
    // Turn Portfolio Tags into pages
    turnPortfolioTagsIntoPages(params),
    // Turn Read Categories into pages.
    turnReadsCategoriesIntoPages(params),
  ]);
}

If I put all these functions into the createPages function, the function would be over 300 lines long. This definitely isn't good for our readability.

Anyway, back on topic. Next, we need to do create the turnBlogPostsIntoPages function that we declared.

So, anywhere above this createPages function add in a new function like so:

async function turnBlogPostsIntoPages({ graphql, actions }) {
  const { createPage } = actions;
}

export async function createPages(params) {
  await Promise.all([turnBlogPostsIntoPages(params)]);
}

Now, we have a function that gets called when the createPages API runs. Let's dive deeper into this function and start making it do something useful.

Here is the finished code which we will break down in a second.

async function turnBlogPostsIntoPages({ graphql, actions }) {
  // 0: Destructuring out the action createPage which is used to create the pages.
  const { createPage } = actions;

  // 1: Query for all of blog post data. Most importantly the totalCount which we will use later on.
  const {
    data: {
      blog: { edges: blogPosts, totalCount: blogTotalCount },
    },
  } = await graphql(`
    query {
      blog: allMdx(filter: { fields: { contentCategory: { eq: "blog" } } }) {
        edges {
          node {
            fields {
              slug
              contentCategory
            }
            frontmatter {
              title
              date(formatString: "DD/MM/YYYY")
            }
          }
        }
        totalCount
      }
    }
  `);

  // 2: Create a page for every blog post node. (This is for indivual blog posts.)
  blogPosts.forEach(({ node }, index) => {
    createPage({
      path: node.fields.slug,
      component: path.resolve("./src/templates/Blog.js"),
      context: {
        slug: node.fields.slug,
        prev: index === 0 ? null : blogPosts[index - 1].node,
        next: index === blogPosts.length - 1 ? null : blogPosts[index + 1].node,
      },
    });
  });

  // 3: Create the main blog pages containing the posts..
  const blogTemplate = path.resolve("./src/pages/blog.js");

  const pageSize = 6; // Total number of posts on each page
  const pageCount = Math.ceil(blogTotalCount / pageSize); // Total number of pages required.

  // Loop through each page required (1 to x) and create a new blog page for each.
  Array.from({ length: pageCount }).forEach((_, i) => {
    createPage({
      path: `/blog/${i === 0 ? "" : i + 1}`,
      blogTemplate,
      // Context is passed to the page so we can skip the required amount of posts on each page.
      context: {
        skip: i * pageSize,
        currentPage: i + 1,
        pageSize,
      },
    });
  });
}

If you have completed the setup of a blog on GatsbyJS you may already have some code that resembles this. Let's break down each step and see what's going on.

This is where we destructure out the createPage action. This is used to actually create the pages from the information we provide.
We query for all the information related to the posts sourced in GraphQL. Most importantly the totalCount number, as this is used to work out how many pages we need later on.
This is where the individual blog posts are created using the createPage action we destructured above.
This is the step we are interested in for this tutorial. This is where we create the paginated blog posts. Let's break this down in more detail below.

Breaking Down the Pagination

Here's the code we are particularly interested in for this tutorial:

const blogTemplate = path.resolve("./src/pages/blog.js");

const pageSize = 6; // Total number of posts on each page
const pageCount = Math.ceil(blogTotalCount / pageSize); // Total number of pages required.

// Loop through each page required (1 to x) and create a new blog page for each.
Array.from({ length: pageCount }).forEach((_, i) => {
  createPage({
    path: `/blog/${i === 0 ? "" : i + 1}`,
    blogTemplate,
    // Context is passed to the page so we can skip the required amount of posts on each page.
    context: {
      skip: i * pageSize,
      currentPage: i + 1,
      pageSize,
    },
  });
});

Let's check out what's going on here.

const blogTemplate = path.resolve("./src/pages/blog.js");

First, we import the template file which we will be using to create all the paginated pages. Note that this is the actual blog page in your pages directory. Not the file used for creating individual posts located within the templates folder.

const pageSize = 6; // Total number of posts on each page
const pageCount = Math.ceil(blogTotalCount / pageSize); // Total number of pages required.

Following this, we create two more variables that will control the page size and how many pages we need. This is achieved by setting the pageSize variable to the number of posts we want on each page. Then we use this variable to work out how many pages we need.

We achieve this by taking the totalnumber from our graphQL query and dividing it by the page size. By rounding up this result it tells us how many pages we need.

Then we get to the juicy part:

// Loop through each page required (1 to x) and create a new blog page for each.
Array.from({ length: pageCount }).forEach((_, i) => {
  createPage({
    path: `/blog/${i === 0 ? "" : i + 1}`,
    blogTemplate,
    // Context is passed to the page so we can skip the required amount of posts on each page.
    context: {
      skip: i * pageSize,
      currentPage: i + 1,
      pageSize,
    },
  });
});

What's going on here?

The most important part of this is what happens on line 2. This is the part that enables us to create multiple blog pages.

Array.from({ length: pageCount }).forEach((_, i) => {});

We have a variable telling us how many pages we need (pageCount). But, for this to be of any use to us, we need to be able to loop through all the numbers leading to this point. This would allow us to create an individual page for each number.

This is where the above line comes in. We use Array.from({ length: pageCount }) to create an array with the length of the number of pages we need to create. Yes, the array items will be blank but that doesn't matter because we are only interested in the indexes.

To get access to the indexes we chain onto the Array.from() with a .forEach((_, i) => {}) like shown above. Because we are only interested in the indexes, we can skip the first argument to forEach. This would represent the actual item (blank) for the index we are currently on in the array. This then allows us access to the second argument which represents the index of the current item.

We are now able to loop through an array of variable length to allow us to create the required number of pages. Now we need to do the actual creation.

Which we can do with the following code:

createPage({
  path: `/blog/${i === 0 ? "" : i + 1}`,
  component: blogTemplate,
  // Context is passed to the page so we can skip the required amount of posts on each page.
  context: {
    skip: i * pageSize,
    currentPage: i + 1,
    pageSize,
  },
});

Let's break down what's going on here.

We are passing a series of arguments to the createPage action, these are:

path: The URL the page will be created for.
component: This is the file that will be used to template out the page.
context: An object containing data passed to the page.
- skip: We pass this to tell the page how many posts to skip in the GraphQL query. We work this out by multiplying the current index of the item we are on by the page size. So page 1 would be: 0 * 6 = 0 and for page 2 it would be: 1 * 6 = 6. This ensures we skip the correct number of posts for each page.
- currentPage: Tells the page what page it currently is which we will use for navigation later on.
- pageSize: The size of the page we defined.

The currentPage context data will make more sense in the final section of this blog post. This is when we will look at creating pagination controls to move between the pages we have created. But, now let's look at the changes we need to make to the page file so it can consume the skip and pageSize context we passed.

Amending the Page File

Now, we have the gatsby-node.js file setup and ready to create all the pages for us. We now need to amend the page file that lists all the posts for us.

Updating the GraphQL Query

First, we need to update the GraphQL query that runs on the page. You should already have something that looks like this:

export const query = graphql`
  query {
    blog: allMdx(
      sort: {
        order: [DESC, DESC]
        fields: [frontmatter___date, frontmatter___id]
      }
      filter: { fields: { contentCategory: { eq: "blog" } } }
    ) {
      edges {
        node {
          fields {
            slug
          }
          frontmatter {
            date(formatString: "DD/MM/YYYY")
            tags
            title
            id
            image {
              childImageSharp {
                fluid(maxWidth: 400) {
                  ...GatsbyImageSharpFluid
                }
              }
            }
          }
        }
      }
      totalCount
    }
  }
`;

The important part to note in this query is that we are fetching all the blog posts. At this point, there are no constraints on the query other than a filter I've done to select all the blog content.

Now, let's look at what we need to add in.

Remember when we edited the gatsby-node.js file we passed a few pieces of context down to the page? Most notably skip and pageSize. Well because we passed them as context to the page we have them available to us to use in GraphQL as variables.

Let's take a look at the amended query and then we'll break them down:

``js{2, 4-5} export const query = graphql
query($skip: Int = 0, $pageSize: Int = 6) {
blog: allMdx(
limit: $pageSize
skip: $skip
sort: {
order: [DESC, DESC]
fields: [frontmatter_date, frontmatter_id]
}
filter: { fields: { contentCategory: { eq: "blog" } } }
) {
edges {
node {
fields {
slug
}
frontmatter {
date(formatString: "DD/MM/YYYY")
tags
title
id
image {
childImageSharp {
fluid(maxWidth: 400) {
...GatsbyImageSharpFluid
}
}
}
}
}
}
totalCount
}
}
`;




As you can see in the top line of the query we added the two variables we passed as context. Let's look at this line in more depth:



```js
query($skip: Int = 0, $pageSize: Int = 6 ) {

If you're unfamiliar with GraphQL syntax. Below is a quick overview of what is happening.

$skip: This is the name of the variable
Int: This is the type of data the variable is
= 0: This is the default value of the variable.

So, in this line, we are taking in two variables which are both Integers (Ints) and giving them a default value.

Now, let's take a look at where they're used in the query:

```js{1, 3-4}
query($skip: Int = 0, $pageSize: Int = 6 ) {
blog: allMdx(
limit: $pageSize
skip: $skip
sort: { order: [DESC, DESC], fields: [frontmatter_date, frontmatter_id] }
filter: { fields: { contentCategory: { eq: "blog" } } }
)
// Rest of the query goes here...
}




As you can see we have added the `skip` and `pageSize` variables. They are passed to the `skip` and `limit` properties of the query.

If we were to translate this to the actual values of page 1, it would look like this:



```js{1, 3-4}
query($skip: Int = 0, $pageSize: Int = 6 ) {
    blog: allMdx(
      limit: 6
      skip: 0
      sort: { order: [DESC, DESC], fields: [frontmatter___date, frontmatter___id] }
      filter: { fields: { contentCategory: { eq: "blog" } } }
    )
    // Rest of the query goes here...
}

This is because we want to limit the results to 6 values and we are skipping 0 because we are on the first page. If we were to look at page 2 as an example, we can start to see how it works.

```js{1, 3-4}
query($skip: Int = 0, $pageSize: Int = 6 ) {
blog: allMdx(
limit: 6
skip: 6
sort: { order: [DESC, DESC], fields: [frontmatter_date, frontmatter_id] }
filter: { fields: { contentCategory: { eq: "blog" } } }
)
// Rest of the query goes here...
}




The only thing that has changed is the skip value. Now, instead of skipping 0 values, we skip the first 6. Then we return a max of 6 values starting from item 7 in the dataset.

This is repeated for every page we generate until we have covered all the posts.

_**NOTE:** If you want your first page to show the latest post you need to use the `sort` property in the query. See my example above for how to sort using the frontmatter\_\_\_date field._

## Pagination Controls

It's great having our posts paginated out over several pages. But, if the only way we have to move between them is by changing the URL we're going to have issues.

This is where adding pagination controls will help us. We're going to add a couple of dedicated buttons that allow next and previous movement on pages. We will also add a list of pages in the middle of the buttons so you can skip pages if you wish.

### Creating the Pagination Component

Before we can implement this into our page we first need to create our `Pagination` component. Let's take a look at the code now.



```js
export default function Pagination({ pageSize, totalCount, currentPage }) {
  const totalPages = Math.ceil(totalCount / pageSize);
  const prevPage = currentPage - 1;
  const nextPage = currentPage + 1;
  const hasNextPage = nextPage <= totalPages;
  const hasPrevPage = prevPage >= 1;

  const prevLink = prevPage === 1 ? "blog" : `blog/${prevPage}`;
  const nextLink = `blog/${nextPage}`;

  return (
    <div>
      <Link title="prev page" disabled={!hasPrevPage} to={prevLink}>
        &#8592; <span className="word">Previous</span>{" "}
      </Link>
      {Array.from({ length: totalPages }).map((_, i) => (
        <Link
          key={`blog-page-${i}`}
          className={currentPage === 1 && i === 0 ? "current" : ""}
          to={`blog/${i === 0 ? "" : i + 1}`}
        >
          {i + 1}
        </Link>
      ))}
      <Link title="next page" disabled={!hasNextPage} to={nextLink}>
        <span className="word">Next</span> &#8594;
      </Link>
    </div>
  );
}

The code isn't too complex, we have a couple of Link elements from Gatsby. Then another one of our Array.from() specials from earlier. This time though instead of using a .forEach() we use a .map() because we want to return the elements.

Let's break this down.

Creating the Links

The first section we are going to take a look at is the code that generates the links for us based on the props we pass in. Here's the code:

export default function Pagination({
  pageSize,
  totalCount,
  currentPage
}) {
  const totalPages = Math.ceil(totalCount / pageSize);
  const prevPage = currentPage - 1;
  const nextPage = currentPage + 1;
  const hasNextPage = nextPage <= totalPages;
  const hasPrevPage = prevPage >= 1;

  const prevLink = prevPage === 1 ? "blog" : `blog/${prevPage}`;
  const nextLink = `blog/${nextPage}`;

  // ... Rest of the component here

So, what are we doing here?

First, we pass in a series of props:

pageSize: The number of posts we want on each page.
totalCount: The total amount of blog posts there are from the GraphQL query on the blog page
currentPage: This comes from the context we added in gatsby-node.js. It is destructured out on the page and then passed down to the component.

After this, we create a series of variables that are used to determine if there is another page to navigate to. And, if so what the URL is.

totalPages: Int: The total amount of pages required
prevPage: Int: Works out the index of the previous page based on the current one.
nextPage: Int: Works out the index of the next page based on the current one.
hasNextPage: Bool: Checks if nextPage is smaller than or equal to totalPages.
hasPrevPage: Bool: Checks if the prevPage variable is greater than or equal to one.

These 5 variables are used throughout the component to decide whether elements should be displayed or not. But, we will come to that in a second. First, we need to create the next and previous links which are our final two variables.

prevLink: Str: Checks if the prevPage variable is equal to one. If so set the variable to 'blog' which will redirect you to the main blog page. If not, set the variable to blog/${prevPage}.
nextLink: Str: This is set to blog/${nextPage}. This is done because we have a separate variable controlling whether there is another page or not.

Now we've covered all the variables required to create the elements, let's look at making the buttons.

Next and Previous Buttons

The code for the previous and next buttons is actually similar with a few word changes. For this reason, I'm only going to break one of them down so we can understand how they both work. First let's look at the complete code so you can see the differences:

<Link title="prev page" disabled={!hasPrevPage} to={prevLink}>
  &#8592; <span className="word">Previous</span>{' '}
</Link>

<Link title="next page" disabled={!hasNextPage} to={nextLink}>
  <span className="word">Next</span> &#8594;
</Link>

The structure of the links is a Gatsby Link element wrapping a span describing what the button does. Let's check out what we do with them:

title: Str: We set a title attribute on the element to declare to the user what each link does.
disabled: Bool: This is where the two variables hasPrevPage and hasNextPage come in. If the variable says that the next or previous page is outside the available pages it will disable the link. This is then styled by CSS to lower the opacity and prevent the user from clicking on them. Check below for this code.
to: Str: This is the destination we want the element to navigate to if clicked.

This covers the functionality, the last part is adding the text elements to label them up on the screen. For this, we use a span wrapping the relevant word and a next/previous arrow depending on the button.

CSS Code to disable the link:

&[disabled] {
      pointer-events: none;
      text-decoration: line-through;
      color: var(--black);
      opacity: 0.5;
    }

Adding All the Pages

We're almost there with the pagination component. We just need to add in the links for each page between the previous and next buttons.

Here's the code for adding in the page links:

{
  Array.from({ length: totalPages }).map((_, i) => (
    <Link
      key={`blog-page-${i}`}
      className={currentPage === 1 && i === 0 ? "current" : ""}
      to={`blog/${i === 0 ? "" : i + 1}`}
    >
      {i + 1}
    </Link>
  ));
}

It's based on a similar principle to what we used in the past for generating each page in gatsby-node.js. However, instead of using a .forEach() to loop over each index, we use a .map() so we can return the Link element.

Let's break down what's happening in this code block:

We create an array with the length equal to totalPages and then map over each index.
We create a Link element and pass 3 props to it:
key: Str: Standard key prop required by React when returning elements from a map.
className: Str: Used to add the 'current' class to the element if we are on that page to allow for styling.
to: Str: The destination we want the link to navigate to.
Finally, we add the text inside the Link which is the index plus 1 to negate the 0-indexing of JavaScript arrays.

Here is the CSS for the current element styling we added:

&[aria-current],
&.current {
  color: var(--green);
  font-weight: 600;
  border-bottom: 2px solid var(--green);
}

Adding to the Page File

We have now created the pagination component, it's time to add it to our blog page file like so:

return (
  <>
    <Pagination
      pageSize={6}
      totalCount={totalCount}
      currentPage={currentPage || 1}
    />
    <AllPostsContainer>
      {blogPosts.map((post) => (
        <BlogPostCard
          key={`blogPostCard-${post.node.frontmatter.id}`}
          post={post}
        />
      ))}
    </AllPostsContainer>
    <Pagination
      pageSize={6}
      totalCount={totalCount}
      currentPage={currentPage || 1}
    />
  </>
);

As we have split the entire pagination component, it's now a matter of passing in the required props:

pageSize: Int: The total number of posts on each page
totalCount: Int: The total number of posts from the GraphQL query.
currentPage: Int: The index of the current page taken from context, if not 1.

We should now be set up and ready to rock and roll.

Summing Up

If everything went to plan you should have something that resembles this for functionality:

I didn't include the CSS in this article apart from one or two sections to try and keep the length of the post down. But, if you're interested in all the CSS it is available on the Github for my website.

One thing I didn't include in this post but do recommend is storing your pageSize variable in a .env file. Then you can import it into Gatsby using parseInt(process.env.GATSBY_PAGE_SIZE)}. This means that should you ever want to change the number of posts per page you only need to change it in one place.

I hope you found this post helpful if you did I would greatly appreciate you sharing it with others on Social Media so they can benefit from it too. If you have any feedback I would love to hear it, you can reach me over on Twitter.

Thanks for reading. 😃

This post was originally published on my blog conermurphy.com. If you're interested in reading my posts as soon as they're released please consider following me on Twitter as well.*

Five Ways to Improve Your Writing As a Developer.

Coner Murphy — Tue, 06 Apr 2021 00:00:00 +0000

This post was originally published on my blog: conermurphy.com if you like my content please consider following me on Twitter @MrConerMurphy for notifications as soon as I publish.

Writing high-quality technical content is a sizeable challenge on its own. But, add in the challenge of ensuring our writing is perfect and it becomes an even larger challenge. For some this is enough for them to put off publishing content all together but it shouldn't be!

In this post, I'll share five ways you can improve your writing to ensure your next article is perfect.

Grammarly

Grammarly is an amazing tool for checking your writing. There are two versions, a free version and a paid version.

The paid version offers features like Conciseness, Readability and Fluency. But, if all you need to do is ensure your writing is free from spelling and grammatical errors the free version is fine.

If you're interested in checking out Grammarly you can here.

Hemingway Editor

The Hemingway Editor checks your writing for style errors. Its aim is to improve the writer's message and allow readers to focus on it easier. It highlights your writing in various colours, each signifying an area to improve.

The web version is completely free to use. But, there is also a desktop app you can purchase here if interested.

Forest

Forest, isn't a writing aid like Grammarly and the Hemingway Editor are.

Instead, Forest is an app and browser extensions that removes distractions and temptations.

It also works as a Pomodoro timer. If you're unfamiliar with a Pomodoro timer, it's a tool that allows you to utilise the Pomodoro Technique. The Pomodoro Technique is working in pre-defined blocks with a smaller period of rest in between. The idea being this helps increase your focus and get more work done.

How will this improve your writing?

I find it easy to get distracted from writing an article. By using Forest it helps me stay focused on the task at hand, in turn helping me write more and improve my writing.

Check out Forest here.

Pick up a book

One of the best ways to improve your writing isn't actually to write at all.

It's to read other people's writing.

I recommend reading as a daily activity in general but improving your writing is a great reason to pick up a book. It doesn't need to be a computer science book or even anything related to coding. It could be non-fiction or a politics book, pick something that interests you and get pulled in.

Reading other people's writing is like reading other people's code. It exposes us to new concepts, ideas and words we haven't seen before. Over time this will give us a larger vocabulary and experience to call upon when writing.

If you would like some recommendations on what to read, you can check out what I've been reading here.

Practise!

Finally, one of the best ways to improve your writing is to write!

Like coding, photography and drawing; at first we're likely not going to be great. But, with time and experience, our skills will improve and so will our writing.

To get started, you could make a daily goal of writing 750 words by completing the Morning Pages project or by writing a blog post a day. At first, it doesn't matter the content, what's important is building up the habit.

Summary / How I Work.

These were five ways to improve your writing as a developer. To conclude I wanted to share my process for writing a blog post and how I use these methods in my own life.

When I write an article, I make a point of doing as little editing as possible while I write. I always separate writing and editing so that when I'm writing I can focus on getting words on the page. This means I leave things like correcting spelling mistakes to the editing stage.

While writing, I go one step further and use VSCode with no spell-checking so all my attention is on writing. I combine this with the Forest App to ensure I'm focused on the task at hand.

After I've finished writing, I'll take a break, I aim for at least one whole day before returning to the post. This isn't always possible though so the least I'll do is a few hours.

This allows me to return with a clear mind and a different mindset to when I was writing.

When editing I move the writing into the Hemingway Editor and make use of the Grammarly browser extension. I start by resolving any Grammarly issues and then look at the issues found by the Hemingway editor.

Once I've fixed all the issues, I'll give the post a read through to ensure it still flows right. This is to ensure I haven't lost the purpose of the article while editing.

After this is complete, it's a matter of creating images and publishing the post. 😃

Thank you for reading! Do you have any tips to help people improve their writing? If so, be sure to share them with me on Twitter. If you found this post helpful, please consider sharing it for others to see.