README.md

go

⚠️ This boilerplate requires configuration before use!!! Follow the instructions below carefully. ⚠️

💰 NOTE: Current running costs are unknown, but I will add these as the data becomes more transparent.

Contents

1. Description
2. Getting Started
   1. Installing dependencies
   2. Configuring your app
   3. Deploying to AWS
   4. Running the frontend
   5. Testing your app

---

Description

This is a boilerplate Golang, NextJS/React application which features the following:

• Go for all the backend and CDK.
  • Middleware pattern and library for lambda function handlers.
  • Hexagonal architecture/adapter based for the backend.
• CDK (written in Golang) to deploy the application to the cloud.
• Lambda serverless functions
• DynamoDB tables and triggers with point in time recovery
• KMS encryption
• Cognito User & Identity Pools
• AWS AppSync authorised and unauthorised access via IAM roles.
• Github Actions
  • Runs go tests
  • Runs frontend tests
  • Synthesises & Runs checkov infrastructure as code
  • Builds the frontend
  • Branch based deployment via CDK to AWS (main, staging)
• Codecov Code coverage for the backend and frontend
• Checkov for infrastructure as code security checks.
• CycloneDX for generating an SBOM
• golangci-lint for static code analysis.
• Pre-Commit for git hook code quality checks.
• NextJS for the frontend.
  • TypeScript
  • React
  • ESLint & Prettier
  • Vitest for unit testing.
  • Cypress for integration testing.
• Apollo GraphQL
  • GraphQL Codegen for generating TypeScript types and Apollo client hooks from our schema automatically.
  • GraphQL Linting for static code analysis.

Project layout

This repository follows these standards for project layout.

TL;DR You'll find:

• Private code in /internal
• Lambda and other command type functions in /cmd
• Frontend in /web

---

Who's this for

This is a boilerplate for creating a serverless application using the AWS AppSync GraphQL API while using Go for the backend and NextJS for the frontend.

Typical audiences are:

• CTO/CEO looking to save time and money getting a good foundation in place.
• Developers and dev-ops teams looking to get started quickly and cheaply.
• Anyone who wants to get a simple serverless application up and running.

Getting started

There are a few steps to getting the most out of this boilerplate:

1. Installing dependencies
2. Adding AWS parameter store values
3. Configuring your app
4. Deploying to AWS
5. Running the frontend
6. Testing your app

---

Installing Dependencies

Before anything, you must have a valid AWS account.

All the AWS services are free for the first year, and you can apply for $300 credit here.

AWS Parameter Store values

To deploy this, the following parameter store values are required to be readable by a cdk user. Substitute {environment} with any of staging, production, ci

/$APP_NAME/{environment}/GITHUB_ACCESS_TOKEN # Secure String
/$APP_NAME/{environment}/OAUTH_CALLBACK_ROOT # String

System dependencies

• Golang 1.18+
• AWS CLI and AWS vault to setup AWS credentials
• direnv to manage environment variables automatically.
• Pre-Commit for git hook code quality checks to prevent bad commits.
• nodeJS & yarn for managing/running frontend dependencies and aws-cdk for the CDK deployments.

Frontend dependencies

The frontend is based on NextJS and React with TypeScript & Vitest and Cypress for testing.

It uses yarn 2.x for managing dependencies.

Running yarn install will install all frontend dependencies.

Read More about the frontend.

Backend dependencies

Go dependencies are managed via Go modules but if you want to download them ahead of time you can run go mod download to download them.

---

Setting up environmentals

Edit ./.envrc and set the following:

APP_NAME            # The name of the application (affects import paths, should be the git repo name.)
NGROK_DOMAIN        # This is the subdomain on ngrok you'll access the frontend from locally.
AWS_REGION          # This is the region you'll be deploying to.
AWS_ACCOUNT_ID      # This is the account you'll be deploying to.
GITHUB_ACCESS_TOKEN # This is the access token you'll use to access the GitHub API.

Go to Github and

1. Generate a new personal access token for the app here
2. Go to repository secrets and add the following:

   ENVIRONMENT
   AWS_REGION
   AWS_ACCOUNT_ID
   GITHUB_ACCESS_TOKEN
   OAUTH_CALLBACK_ROOT
   CODECOV_TOKEN

---

Configuring your app

You should have the dependencies' installation instructions AND the environmentals instructions completed above to continue, you should be able to run init-project which will rename this project to match your Git repository name.

Deployment

The CDK supports creating stacks per any environment, supported environments are production, staging, ci

deploy

Or you can deploy a specific environment with

ENVIRONMENT={production, staging, ci} deploy