Plausible Analytics requires access to the window object to track 404 events. So create a client component.

'use client';

import Script from "next/script";

export default function FourOhFourEvent() {
    return <Script onReady={() => window.plausible('404', { props: { path: window.location.pathname } })} />
}

Then create app/not-found.tsx:

import FourOhFourEvent from "./path/to/component/FourOhFourEvent";

export default function Page() {
    return (
        <>
            <FourOhFourEvent />
            <h1>Not Found</h1>
        </>
    )
}

A minor benefit is that visitors can make mistakes typing your domain and still get where they need to go. A major benefit is mitigating phishing attacks.

A classic example that I have recently seen is DHL phishing attacks. They'll send a text message claiming that you need to pay tariffs on an international shipment before it clears customs. You land on a domain name like dlh.com instead of dhl.com and enter your credit card number to realize their site is broken. Then the real bad news settles in.

Thankfully a totally more legitimate company in another industry owns dlh.com. But the lesson remains important nevertheless.

Lesson aside, how do you manage this at scale when you're using Terraform and Cloudflare? Create a module that implements a Cloudflare Redirect Rule for a Cloudflare Zone. Add a main.tf, variables.tf, and outputs.tf file for said module.

# ./modules/domain_redirect/variables.tf
variable cloudflare_account_id {
  type = string
}

variable origin {
  type = string
  description = "Source hostname"
}

variable destination {
  type = string
  description = "Target hostname"
}

# ./modules/domain_redirect/main.tf
terraform {
  required_providers {
    cloudflare = {
      source  = "cloudflare/cloudflare"
      version = "~> 4.21.0"
    }
  }
}

resource cloudflare_zone zone {
  account_id = var.cloudflare_account_id
  zone = "${var.origin}"
}

resource cloudflare_record stub {
  zone_id = cloudflare_zone.zone.id
  comment = "Stubbed record needed to trigger DNS resolution and subsequent redirect"
  type = "A"
  name = "@"
  value = "192.0.2.1"
  proxied = true
  ttl = 1
}

resource cloudflare_ruleset redirect {
  zone_id = cloudflare_zone.zone.id
  name = "Hostname redirect to ${var.destination}"
  kind = "zone"
  phase = "http_request_dynamic_redirect"
  rules {
    action = "redirect"
    action_parameters {
      from_value {
        status_code = 301
        target_url {
          value = "https://${var.destination}"
        }
        preserve_query_string = true
      }
    }
    expression  = "http.host eq \"${var.origin}\""
    description = "Redirect all requests from ${var.origin} to ${var.destination}"
    enabled     = true
  }
}

You'll notice the DNS record above is called a stub. This is because Cloudflare does not execute any rulesets for a given zone until there is at least one root A or CNAME record. In my example above, I use a reserved IPv4 address belonging to the TEST-NET-1 IP block designated for documentation purposes by the IANA.

And in your parent main.tf file, you can use a for_each loop to map over every redirect you need to implement like so:

# ./main.tf
variable domain_redirects {
  type = map(string)
  default = {
    "example1.com" = "example.com"
    "example2.com" = "example.com"
    "example1.fr" = "example.fr"
  }
}

module domain_redirects {
  cloudflare_account_id = local.cloudflare_account_id
  source = "./modules/domain_redirect"
  for_each = var.domain_redirects
  origin = each.key
  destination = each.value
}

The benefit of this map(string) type variable is also that you can have multiple destinations in case your company has canonical domains for different use cases (like example.ai) or regions (like example.fr).

Lastly, you'll want to create an output value so that you'll see a more human-readable result for your domain-level redirects. First, you'll need to create an outputs file for your module:

#./module/domain_redirect/outputs.tf
output domain_redirect {
  value = cloudflare_ruleset.redirect.rules[0].action_parameters[0].from_value[0].target_url[0].value
}

And then add another outputs.tf file to the parent folder where your domain_redirect module is used:

# ./outputs.tf
output domain_redirects {
  value = { for domain, redirect in module.domain_redirects : domain => redirect.domain_redirect }
  description = "The target URLs for each domain redirect"
}

After that, you get human readable output when you run your terraform plan command.

module.domain_redirects["example1.com"].cloudflare_zone.zone: Refreshing state... [id=...]
module.domain_redirects["example1.com"].cloudflare_record.stub: Refreshing state... [id=...]
module.domain_redirects["example1.com"].cloudflare_ruleset.redirect: Refreshing state... [id=...]
module.domain_redirects["example2.com"].cloudflare_zone.zone: Refreshing state... [id=...]
module.domain_redirects["example2.com"].cloudflare_record.stub: Refreshing state... [id=...]
module.domain_redirects["example2.com"].cloudflare_ruleset.redirect: Refreshing state... [id=...]
module.domain_redirects["example1.fr"].cloudflare_zone.zone: Refreshing state... [id=...]
module.domain_redirects["example1.fr"].cloudflare_record.stub: Refreshing state... [id=...]
module.domain_redirects["example1.fr"].cloudflare_ruleset.redirect: Refreshing state... [id=...]
Apply complete! Resources: 0 added, 0 changed, 0 destroyed.

Outputs:

domain_redirects = {
  "example1.com" = "https://example.com"
  "example2.com" = "https://example.com"
  "example1.fr" = "https://example.fr"
}

That's it!

Plan: 1 to add, 0 to change, 1 to destroy.

But you didn't add a new resource. And there's still data in your S3 bucket. Destroying the bucket would far from ideal. How do we tell Terraform that we don't want to replace the resource but simply rename it?

Let's walk through a straightforward example: a super generic S3 bucket declaration.

resource aws_s3_bucket s3_bucket {
  bucket = "assets"
}

At some point, you apply your terraform changes. But you forgot something. You realize the S3 bucket name is too generic. So you rename your S3 bucket to something specific so you can better remember its purpose:

resource aws_s3_bucket very_specific_s3_bucket {
  bucket = "assets"
}

Now you run terraform plan to see the expected changes when you see the dreaded message: Plan: 1 to add, 0 to change, 1 to destroy.

$ terraform plan
Terraform will perform the following actions:

  # aws_s3_bucket.very_specific_s3_bucket will be created
  + resource "aws_s3_bucket" "very_specific_s3_bucket" {
      + acceleration_status         = (known after apply)
      + acl                         = (known after apply)
      + arn                         = (known after apply)
      + bucket                      = "assets"
      + bucket_domain_name          = (known after apply)
      + bucket_regional_domain_name = (known after apply)
      + force_destroy               = false
      + hosted_zone_id              = (known after apply)
      + id                          = (known after apply)
      + object_lock_enabled         = (known after apply)
      + policy                      = (known after apply)
      + region                      = (known after apply)
      + request_payer               = (known after apply)
      + tags_all                    = {
          + "CreatedBy"   = "terraform"
        }
      + website_domain              = (known after apply)
      + website_endpoint            = (known after apply)
    }

  # aws_s3_bucket.s3_bucket will be destroyed
  # (because aws_s3_bucket.s3_bucket is not in configuration)
  - resource "aws_s3_bucket" "s3_bucket" {
      - arn                         = "arn:aws:s3:::assets" -> null
      - bucket                      = "assets" -> null
      - bucket_domain_name          = "assets.s3.amazonaws.com" -> null
      - bucket_regional_domain_name = "assets.s3.amazonaws.com" -> null
      - force_destroy               = false -> null
      - hosted_zone_id              = "..." -> null
      - id                          = "assets" -> null
      - object_lock_enabled         = false -> null
      - region                      = "us-east-1" -> null
      - request_payer               = "BucketOwner" -> null
      - tags                        = {} -> null
      - tags_all                    = {
          - "CreatedBy"   = "terraform"
        } -> null
      - grant {
          - id          = "..." -> null
          - permissions = [
              - "FULL_CONTROL",
            ] -> null
          - type        = "CanonicalUser" -> null
        }
      - server_side_encryption_configuration {
          - rule {
              - bucket_key_enabled = false -> null
              - apply_server_side_encryption_by_default {
                  - sse_algorithm = "AES256" -> null
                }
            }
        }
      - versioning {
          - enabled    = false -> null
          - mfa_delete = false -> null
        }
    }
Plan: 1 to add, 0 to change, 1 to destroy.

How do you fix this? Start by adding this line:

moved {
  from = aws_s3_bucket.s3_bucket
  to = aws_s3_bucket.very_specific_s3_bucket
}

Then run terraform plan to see if your terraform output changes. You should see this output upon running the plan command:

  # aws_s3_bucket.s3_bucket has moved to aws_s3_bucket.very_specific_s3_bucket
    resource "aws_s3_bucket" "very_specific_s3_bucket" {
        id                          = "assets"
        tags                        = {}
        # (10 unchanged attributes hidden)

        # (3 unchanged blocks hidden)
    }

Now that you've validated your Terraform state will be updated to reflect this resource reference change, you can confidently run terraform apply without fear that your S3 bucket will be accidentally destroyed. Once the changes are applied successfully, you can remove the moved {} block. No subsequent terraform apply is necessary.

But what about terraform state mv?

An alternative to using the moved { ... } block is the terraform state mv command. But using it runs counter to the intent of terraform. By running this command, you lose the chance to see your changes planned before they're applied. Without that, it's very easy to make mistakes. Whereas using the moved {} block allows you to perform a dry run of your changes and confirm that you will not accidentally make an disruptive change.

If you're still not convinced that the moved {} block is the better solution, consider why you're even using Terraform in the first place: "infrastructure as code". When submitting a pull request for your code changes, it should be clear to the person reviewing the changes before you actually make the change. You can always submit a subsequent pull request to delete the moved blocks after you've confirmed that the resource name changes have been successfully applied. If neither of my reasons convince you, Terraform is probably not the right tool for you.

Despite having said that, I'll explain one caveat...

Okay but what about for_each loops?

There's one exception to that rule that I've seen so far. And it's not really an exception if you're using the latest stable release of Terraform (which is v1.6.6 as of this writing).

For versions as recent as v1.5.7, the moved { ... } block does not work when applied to resources created using a for_each loop. This isn't ideal if your infrastructure is sufficiently large enough because it's annoying to repeat yourself.

Here's a basic example:

resource aws_s3_bucket s3_bucket {
  bucket = "assets"
}
moved {
  from = aws_s3_bucket.s3_bucket
  to = aws_s3_bucket.all_my_s3_buckets["very_specific_s3_bucket"]
}

resource aws_s3_bucket second_s3_bucket {
  bucket = "other-assets"
}
moved {
  from = aws_s3_bucket.second_s3_bucket
  to = aws_s3_bucket.all_my_s3_buckets["another_s3_bucket"]
}

variable lots_of_buckets {
  type = map(string)
  default = {
    "very_specific_s3_bucket": "assets",
    "another_s3_bucket": "other-assets"
  }
}
resource aws_s3_bucket all_my_s3_buckets {
  for_each = var.lots_of_buckets
  bucket   = each.value
}

Here, I've defined two S3 buckets and I've consolidated them because they're configured exactly the same way with the exception of their bucket names.

How will Terraform behave when you do this? You'll get this message:

Plan: 2 to add, 0 to change, 2 to destroy.

But why? I don't know. But suffice it to say there's probably an article about it somewhere else. I'll limit my discussion to when it's ACTUALLY worth using the terraform state mv command.

This is what the output of terraform plan will look like when trying to move distinct resource declarations into a for_each loop:

$ terraform plan
Terraform will perform the following actions:

  # aws_s3_bucket.all_my_s3_buckets["very_specific_s3_bucket"] will be created
  + resource "aws_s3_bucket" "all_my_s3_buckets" {
      + acceleration_status         = (known after apply)
      + acl                         = (known after apply)
      + arn                         = (known after apply)
      + bucket                      = "assets"
      + bucket_domain_name          = (known after apply)
      + bucket_regional_domain_name = (known after apply)
      + force_destroy               = false
      + hosted_zone_id              = (known after apply)
      + id                          = (known after apply)
      + object_lock_enabled         = (known after apply)
      + policy                      = (known after apply)
      + region                      = (known after apply)
      + request_payer               = (known after apply)
      + tags_all                    = {
          + "CreatedBy"   = "terraform"
        }
      + website_domain              = (known after apply)
      + website_endpoint            = (known after apply)
    }

  # aws_s3_bucket.very_specific_s3_bucket will be destroyed
  # (because aws_s3_bucket.very_specific_s3_bucket was moved to aws_s3_bucket.all_my_s3_buckets["very_specific_s3_bucket"], which is not in configuration)
  # (moved from aws_s3_bucket.very_specific_s3_bucket)
  - resource "aws_s3_bucket" "very_specific_s3_bucket" {
      - arn                         = "arn:aws:s3:::assets" -> null
      - bucket                      = "assets" -> null
      - bucket_domain_name          = "assets.s3.amazonaws.com" -> null
      - bucket_regional_domain_name = "assets.s3.amazonaws.com" -> null
      - force_destroy               = false -> null
      - hosted_zone_id              = "..." -> null
      - id                          = "assets" -> null
      - object_lock_enabled         = false -> null
      - region                      = "us-east-1" -> null
      - request_payer               = "BucketOwner" -> null
      - tags                        = {} -> null
      - tags_all                    = {
          - "CreatedBy"   = "terraform"
        } -> null
      - grant {
          - id          = "..." -> null
          - permissions = [
              - "FULL_CONTROL",
            ] -> null
          - type        = "CanonicalUser" -> null
        }
      - server_side_encryption_configuration {
          - rule {
              - bucket_key_enabled = false -> null
              - apply_server_side_encryption_by_default {
                  - sse_algorithm = "AES256" -> null
                }
            }
        }
      - versioning {
          - enabled    = false -> null
          - mfa_delete = false -> null
        }
    }

  # aws_s3_bucket.all_my_s3_buckets["another_s3_bucket"] will be created
  + resource "aws_s3_bucket" "all_my_s3_buckets" {
      + acceleration_status         = (known after apply)
      + acl                         = (known after apply)
      + arn                         = (known after apply)
      + bucket                      = "other-assets"
      + bucket_domain_name          = (known after apply)
      + bucket_regional_domain_name = (known after apply)
      + force_destroy               = false
      + hosted_zone_id              = (known after apply)
      + id                          = (known after apply)
      + object_lock_enabled         = (known after apply)
      + policy                      = (known after apply)
      + region                      = (known after apply)
      + request_payer               = (known after apply)
      + tags_all                    = {
          + "CreatedBy"   = "terraform"
        }
      + website_domain              = (known after apply)
      + website_endpoint            = (known after apply)
    }

  # aws_s3_bucket.another_s3_bucket will be destroyed
  # (because aws_s3_bucket.another_s3_bucket was moved to aws_s3_bucket.all_my_s3_buckets["another_s3_bucket"], which is not in configuration)
  # (moved from aws_s3_bucket.another_s3_bucket)
  - resource "aws_s3_bucket" "another_s3_bucket" {
      - arn                         = "arn:aws:s3:::assets" -> null
      - bucket                      = "other-assets" -> null
      - bucket_domain_name          = "other-assets.s3.amazonaws.com" -> null
      - bucket_regional_domain_name = "other-assets.s3.amazonaws.com" -> null
      - force_destroy               = false -> null
      - hosted_zone_id              = "..." -> null
      - id                          = "other-assets" -> null
      - object_lock_enabled         = false -> null
      - region                      = "us-east-1" -> null
      - request_payer               = "BucketOwner" -> null
      - tags                        = {} -> null
      - tags_all                    = {
          - "CreatedBy"   = "terraform"
        } -> null
      - grant {
          - id          = "..." -> null
          - permissions = [
              - "FULL_CONTROL",
            ] -> null
          - type        = "CanonicalUser" -> null
        }
      - server_side_encryption_configuration {
          - rule {
              - bucket_key_enabled = false -> null
              - apply_server_side_encryption_by_default {
                  - sse_algorithm = "AES256" -> null
                }
            }
        }
      - versioning {
          - enabled    = false -> null
          - mfa_delete = false -> null
        }
    }
Plan: 2 to add, 0 to change, 2 to destroy.

How do you solve this?

$ terraform state mv 'aws_s3_bucket.very_specific_s3_bucket' 'aws_s3_bucket.all_my_s3_buckets["very_specific_s3_bucket"]')
Move "aws_s3_bucket.very_specific_s3_bucket" to "aws_s3_bucket.all_my_s3_buckets[\"very_specific_s3_bucket\"]"
Successfully moved 1 object(s).
Releasing state lock. This may take a few moments...

$ terraform state mv 'aws_s3_bucket.another_s3_bucket' 'aws_s3_bucket.all_my_s3_buckets["another_s3_bucket"]')
Move "aws_s3_bucket.another_s3_bucket" to "aws_s3_bucket.all_my_s3_buckets[\"another_s3_bucket\"]"
Successfully moved 1 object(s).
Releasing state lock. This may take a few moments...

That's about it. Drop me a message on Mastodon if you have feedback.