README.yaml

#
# This is the canonical configuration for the `README.md`
# Run `make readme` to rebuild the `README.md`
#

# Name of this project
name: terraform-aws-amplify-app

# Logo for this project
#logo: docs/logo.png

# License of this project
license: "APACHE2"

# Copyrights
copyrights:
  - name: "Cloud Posse, LLC"
    url: "https://cloudposse.com"
    year: "2023"

# Canonical GitHub repo
github_repo: cloudposse/terraform-aws-amplify-app

# Badges to display
badges:
  - name: Latest Release
    image: https://img.shields.io/github/release/cloudposse/terraform-aws-amplify-app.svg?style=for-the-badge
    url: https://github.com/cloudposse/terraform-aws-amplify-app/releases/latest
  - name: Last Updated
    image: https://img.shields.io/github/last-commit/cloudposse/terraform-aws-amplify-app.svg?style=for-the-badge
    url: https://github.com/cloudposse/terraform-aws-amplify-app/commits
  - name: Slack Community
    image: https://slack.cloudposse.com/for-the-badge.svg
    url: https://slack.cloudposse.com

# List any related terraform modules that this module may be used with or that this module depends on.
related:
  - name: "terraform-null-label"
    description: "Terraform module designed to generate consistent names and tags for resources. Use terraform-null-label to implement a strict naming convention."
    url: "https://github.com/cloudposse/terraform-null-label"

# List any resources helpful for someone to get started. For example, link to the hashicorp documentation or AWS documentation.
references:
  - name: "AWS Amplify Documentation"
    url: "https://docs.aws.amazon.com/amplify/index.html"
    description: "Use AWS Amplify to develop and deploy cloud-powered mobile and web apps"
  - name: "Setting up Amplify access to GitHub repositories"
    url: "https://docs.aws.amazon.com/amplify/latest/userguide/setting-up-GitHub-access.html"
    description: "Amplify uses the GitHub Apps feature to authorize Amplify read-only access to GitHub repositories. With the Amplify GitHub App, permissions are more fine-tuned, enabling you to grant Amplify access to only the repositories that you specify"
  - name: "Getting started with existing code"
    url: "https://docs.aws.amazon.com/amplify/latest/userguide/getting-started.html"
    description: "Documentation on how to continuously build, deploy, and host a modern web app using existing code"
  - name: "Deploy a Web App on AWS Amplify"
    url: "https://aws.amazon.com/getting-started/guides/deploy-webapp-amplify/"
    description: "A guide on deploying a web application with AWS Amplify"
  - name: "Getting started with fullstack continuous deployments"
    url: "https://docs.aws.amazon.com/amplify/latest/userguide/deploy-backend.html"
    description: "Tutorial on how to set up a fullstack CI/CD workflow with Amplify"
  - name: "Cloud Posse Documentation"
    url: "https://docs.cloudposse.com"
    description: "The Cloud Posse Developer Hub (documentation)"
  - name: "Terraform Standard Module Structure"
    description: "HashiCorp's standard module structure is a file and directory layout we recommend for reusable modules distributed in separate repositories."
    url: "https://www.terraform.io/docs/language/modules/develop/structure.html"
  - name: "Terraform Module Requirements"
    description: "HashiCorp's guidance on all the requirements for publishing a module. Meeting the requirements for publishing a module is extremely easy."
    url: "https://www.terraform.io/docs/registry/modules/publish.html#requirements"
  - name: "Terraform Version Pinning"
    description: "The required_version setting can be used to constrain which versions of the Terraform CLI can be used with your configuration"
    url: "https://www.terraform.io/docs/language/settings/index.html#specifying-a-required-terraform-version"
  - name: "Masterpoint.io"
    description: "This repo was inspired by masterpoint's original amplify-app terraform module"
    url: https://github.com/masterpointio/terraform-aws-amplify-app/

# Short description of this project
description: |-
  Terraform module to provision AWS Amplify apps, backend environments, branches, domain associations, and webhooks. 

# How to use this module. Should be an easy example to copy and paste.
usage: |-
  For a complete example, see [examples/complete](examples/complete).

  For automated tests of the complete example using [bats](https://github.com/bats-core/bats-core) and [Terratest](https://github.com/gruntwork-io/terratest)
  (which tests and deploys the example on AWS), see [test](test).

  ```hcl
  data "aws_ssm_parameter" "github_pat" {
    name            = var.github_personal_access_token_secret_path
    with_decryption = true
  }

  module "amplify_app" {
    source  = "cloudposse/amplify-app/aws"
    # Cloud Posse recommends pinning every module to a specific version
    # version = "x.x.x"

    access_token = data.aws_ssm_parameter.github_pat.value

    description  = "Test Amplify App"
    repository   = "https://github.com/cloudposse/amplify-test2"
    platform     = "WEB"

    enable_auto_branch_creation = false
    enable_branch_auto_build    = true
    enable_branch_auto_deletion = true
    enable_basic_auth           = false

    iam_service_role_enabled    = true

    iam_service_role_actions = [
      "logs:CreateLogStream",
      "logs:CreateLogGroup",
      "logs:DescribeLogGroups",
      "logs:PutLogEvents"
    ]

    auto_branch_creation_patterns = [
      "*",
      "*/**"
    ]

    auto_branch_creation_config = {
      # Enable auto build for the created branches
      enable_auto_build = true
    }

    # The build spec for React
    build_spec = <<-EOT
      version: 0.1
      frontend:
        phases:
          preBuild:
            commands:
              - yarn install
          build:
            commands:
              - yarn run build
        artifacts:
          baseDirectory: build
          files:
            - '**/*'
        cache:
          paths:
            - node_modules/**/*
    EOT

    custom_rules = [
      {
        source = "/<*>"
        status = "404"
        target = "/index.html"
      }
    ]

    environment_variables = {
      ENV = "test"
    }

    environments = {
      main = {
        branch_name                 = "main"
        enable_auto_build           = true
        backend_enabled             = false
        enable_performance_mode     = true
        enable_pull_request_preview = false
        framework                   = "React"
        stage                       = "PRODUCTION"
      }
      dev = {
        branch_name                 = "dev"
        enable_auto_build           = true
        backend_enabled             = false
        enable_performance_mode     = false
        enable_pull_request_preview = true
        framework                   = "React"
        stage                       = "DEVELOPMENT"
      }
    }

    domains = {
      "test.net" = {
        enable_auto_sub_domain = true
        wait_for_verification  = false
        sub_domain = [
          {
            branch_name = "main"
            prefix      = ""
          },
          {
            branch_name = "dev"
            prefix      = "dev"
          }
        ]
      }
    }

    context = module.label.context
  }
  ```

# Example usage
examples: |-
  Here is an example of using this module:
  - [`examples/complete`](https://github.com/cloudposse/terraform-aws-amplify-app/) - complete example of using this module

# Other files to include in this README from the project folder
include:
  - "docs/targets.md"
  - "docs/terraform.md"

# Contributors to this project
contributors: []