Webflow Proxy Generator

A powerful Yeoman generator that creates production-ready Webflow proxy infrastructure on AWS or CloudFlare with support for multi-locale websites, vanity URLs, and automated deployments.

Features

• Multi-Cloud Support: Deploy on AWS (CloudFront + Lambda@Edge) or CloudFlare (Workers)
• Multi-Locale Support: Handle multiple languages and regions with automatic redirects
• Vanity URL Support: Custom short URLs with DynamoDB (AWS) or KV storage (CloudFlare)
• Automated Deployments: GitHub Actions CI/CD with environment-specific configurations
• SEO Optimized: Dynamic sitemap generation, robots.txt management, and URL normalization
• Production Ready: Security headers, caching strategies, and monitoring built-in

Prerequisites

• Node.js 20.x or higher
• npm or yarn
• Git
• Terraform and Terragrunt (for CloudFlare deployments)

Installation

Install Yeoman and the generator globally:

npm install -g yo generator-webflow-proxy

Usage

Create a new project:

mkdir my-webflow-project
cd my-webflow-project
yo webflow-proxy

Answer the interactive prompts to configure your project.

Configuration Prompts

The generator will ask you:

1. Brand/Company name: Your brand identifier (e.g., ACME)
2. Project name: Lowercase, alphanumeric with hyphens
3. Cloud provider: AWS or CloudFlare
4. Multiple locales support: Yes/No
5. Locales file path: (if locales enabled) Path to your JSON configuration file
6. Default locale: (if locales enabled) e.g., en-us
7. Vanity URL support: Yes/No - Custom short URLs for marketing campaigns
8. Site domain: e.g., example.com
9. Webflow domain pattern:
   • Environment-specific: webflow.{env}.example.com (each env gets its own Webflow domain)
   • Single domain: webflow.example.com (all environments use the same Webflow domain)
10. Environments: Select which environments to configure (dev, sit, uat, prod)
11. AWS Account ID: (if AWS) 12-digit account ID
12. AWS Region: (if AWS) e.g., us-east-1
13. CloudFlare Account ID: (if CloudFlare)
14. CloudFlare Zone ID: (if CloudFlare)

Locales Configuration File

If you enable locale support, create a JSON file with your supported locales:

{
  "pr": {
    "default-locale": ["es-pr", "en-pr"]
  },
  "ca": {
    "default-locale": ["en-ca", "fr-ca"]
  },
  "us": {
    "default-locale": ["en-us"]
  },
  "mx": {
    "default-locale": ["es-mx"]
  }
}

Save this as locales.json and provide the path when prompted.

Vanity URL Support

When enabled, the generator creates infrastructure to support custom short URLs:

AWS Implementation

• DynamoDB Table: Stores vanity URL mappings
• Lambda@Edge: Checks for vanity URLs on each request
• Automatic Redirects: Seamless redirects to target URLs

CloudFlare Implementation

• KV Storage: Stores vanity URL mappings
• Workers: Edge-based vanity URL processing
• Global Performance: Sub-10ms response times

Usage Examples

# Add a vanity URL (AWS)
aws dynamodb put-item \
  --table-name myapp-vanity-urls \
  --item '{"vanity_path": {"S": "/promo"}, "target_path": {"S": "/en-us/special-offer"}}'

# Add a vanity URL (CloudFlare)
wrangler kv:key put "promo" "/en-us/special-offer" --binding VANITY_URLS

How it works:

• When a user visits /promo, the system checks if this path exists in the vanity URL table
• If found, it fetches the content from /en-us/special-offer instead of redirecting
• If not found, it continues with normal origin fetching
• This provides seamless vanity URLs without redirects or URL changes in the browser

Environment and Branch Mapping

The generator automatically maps environments to Git branches:

• dev -> develop branch
• sit -> sit branch
• uat -> uat branch
• prod -> main branch

AWS-Specific Setup

Prerequisites

• AWS CLI installed and configured
• AWS account with appropriate permissions
• Domain hosted in Route53 (or DNS managed externally)

GitHub Secrets

AWS_ROLE_ARN=arn:aws:iam::ACCOUNT:role/GitHubActionsRole
AWS_CERTIFICATE_ARN=arn:aws:acm:us-east-1:ACCOUNT:certificate/xxx (optional)

GitHub Variables

Configure these as GitHub repository variables:

BRAND=your_brand_name
PROJECT_NAME=your_project_name
SITE_DOMAIN=example.com
WEBFLOW_DOMAIN=webflow.example.com

Note: The GitHub Actions workflow will compute environment-specific domains automatically (e.g., dev.example.com for dev environment).

First Deployment

cd aws
npm install
npx cdk bootstrap aws://ACCOUNT/REGION
npx cdk deploy --all

CloudFlare-Specific Setup

Prerequisites

• CloudFlare account
• Domain added to CloudFlare
• API Token with appropriate permissions (Zone:Edit, Workers:Edit, DNS:Edit)
• Terraform and Terragrunt installed

Terragrunt and Terraform Backend Configuration

The generator uses Terragrunt for environment management and DRY Terraform configurations. You MUST configure a remote backend for Terraform state management.

Directory Structure

<project-name>/
├── modules/
│   └── cloudflare/          # Terraform modules and configurations
│       ├── main.tf
│       ├── variables.tf
│       ├── workers.tf
│       └── workers/         # Worker scripts
│           ├── proxy/
│           ├── sitemap/
│           └── robots/
└── live/                    # Terragrunt live configurations
    ├── root.hcl             # Root configuration
    └── <env>/               # Environment-specific configs
        └── terragrunt.hcl   # Per-environment settings

Backend Configuration Options

Update <project-name>/live/root.hcl to configure your backend:

Option 1: AWS S3 Backend (Default)

locals {
  brand        = "your-brand"
  project_name = "your-project-name"
}

remote_state {
  backend = "s3"
  generate = {
    path      = "backend.tf"
    if_exists = "overwrite_terragrunt"
  }
  config = {
    bucket         = "your-brand-terraform-state"
    key            = "${local.brand}/${local.project_name}/${path_relative_to_include()}/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "your-brand-terraform-locks"
  }
}

inputs = {
  brand        = local.brand
  project_name = local.project_name
  # default_locale = "en-us" # Only if using locales
}

Option 2: Terraform Cloud

remote_state {
  backend = "remote"
  generate = {
    path      = "backend.tf"
    if_exists = "overwrite_terragrunt"
  }
  config = {
    organization = "your-org-name"
    
    workspaces {
      prefix = "${local.brand}-${local.project_name}-"
    }
  }
}

Option 3: Cloudflare R2

remote_state {
  backend = "s3"
  generate = {
    path      = "backend.tf"
    if_exists = "overwrite_terragrunt"
  }
  config = {
    bucket                      = "terraform-state"
    key                         = "${local.brand}/${local.project_name}/${path_relative_to_include()}/terraform.tfstate"
    region                      = "auto"
    skip_credentials_validation = true
    skip_metadata_api_check     = true
    skip_region_validation      = true
    use_path_style              = true
    endpoints = {
      s3 = "https://<account-id>.r2.cloudflarestorage.com"
    }
  }
}

GitHub Secrets

CLOUDFLARE_API_TOKEN=your_api_token_here
TF_API_TOKEN=your_terraform_cloud_token (if using Terraform Cloud)

GitHub Variables

Configure these at the repository level:

CLOUDFLARE_ACCOUNT_ID=your_account_id
CLOUDFLARE_ZONE_ID=your_zone_id
BRAND=your_brand_name
PROJECT_NAME=your_project_name
SITE_DOMAIN=example.com
WEBFLOW_DOMAIN=webflow.example.com
DEFAULT_LOCALE=en-us (only if using locales)

How it works:

• SITE_DOMAIN and WEBFLOW_DOMAIN should be set to the base production domains
• Environment variables are passed to Terragrunt via TG_VAR_* and TF_VAR_*
• Terragrunt handles environment-specific domain computation (e.g., adding dev. prefix for non-prod)
• All variables are injected at deployment time

Example:

• Repository variable: SITE_DOMAIN=acme.com
• Deployment to dev: Terragrunt receives site_domain=acme.com and environment=dev
• Terragrunt computes: dev.acme.com for the actual DNS record

Environment Management

Terragrunt manages multiple environments through environment-specific terragrunt.hcl files:

• Each environment (dev, sit, uat, prod) has its own directory under live/<env>/
• Each live/<env>/terragrunt.hcl includes the root configuration and adds environment-specific inputs
• The terraform.source points to the shared modules in modules/cloudflare
• Environment-specific values (site_domain, webflow_domain, environment) are passed as inputs
• State files are isolated per environment in your configured backend

Example environment configuration (live/dev/terragrunt.hcl):

include "root" {
  path = find_in_parent_folders("root.hcl")
}

terraform {
  source = "${get_repo_root()}/your-project-name/modules/cloudflare"
}

inputs = {
  site_domain    = "dev.example.com"
  webflow_domain = "webflow.dev.example.com"
  environment    = "dev"
}

First Deployment

Using Terragrunt (recommended):

cd <project-name>/live/<env>
terragrunt init
terragrunt plan
terragrunt apply

Or use GitHub Actions by pushing to the appropriate branch (develop, sit, uat, main).

Common Tasks

Update Environment-Specific Configuration

Environment-specific values are computed dynamically:

• Production: example.com, webflow.example.com
• Dev: dev.example.com, webflow.dev.example.com
• UAT: uat.example.com, webflow.uat.example.com

Add New Locale

1. Update the locales configuration:
   • AWS: Edit origin-request-lambda/handler/supported-countries.json
   • CloudFlare: Update the supportedLocales in both the proxy and sitemap workers
2. Redeploy infrastructure

Update Static Files (AWS only)

1. Edit files in aws/lib/resources/proxy/static-files/{env}/
2. Redeploy proxy stack

Regenerate Sitemap

The sitemap regenerates automatically on Webflow publish events.

Manual regeneration:

• AWS: Invoke webhook Lambda manually
• CloudFlare: Workers regenerate on request

Troubleshooting

Generator Not Found

npm install -g yo generator-webflow-proxy

CDK Deployment Fails

• Check AWS credentials
• Verify environment variables
• Check CloudFormation console for detailed errors

Terragrunt/Terraform State Issues

If you encounter state-related errors:

• Ensure backend is properly configured in root.hcl
• Verify Terragrunt can access the backend
• Check backend connectivity (S3/Terraform Cloud)
• Run terragrunt init to reinitialize

Workers Not Deploying

• Verify API token permissions
• Check CloudFlare account and zone IDs
• Review GitHub Actions logs for specific errors

Example Usage

# Install generator
npm install -g yo generator-webflow-proxy

# Create new project
mkdir acme-website-proxy
cd acme-website-proxy
yo webflow-proxy

# Follow prompts:
? Brand/Company name: ACME
? Project name: acme-website-proxy
? Cloud provider: CloudFlare
? Multiple locales? Yes
? Locales file: ./locales.json
? Default locale: en-us
? Vanity URLs? No
? Site domain: acme.com
? Webflow pattern: webflow.{env}.acme.com
? Environments: dev, uat, prod
? CloudFlare Account ID: abc123def456
? CloudFlare Zone ID: xyz789

# Project created successfully!

Next Steps

1. Review generated files
2. Configure Terragrunt backend in <project-name>/live/root.hcl (for CloudFlare)
3. Configure GitHub repository secrets and variables
4. Commit and push to GitHub
5. Monitor GitHub Actions deployment
6. Configure Webflow webhook (AWS only)
7. Test the deployed infrastructure

Important Notes

• CloudFlare deployments use Terragrunt for environment management
• CloudFlare deployments require a remote Terraform backend
• Environment-specific domains are computed automatically
• GitHub Actions workflows are environment-aware and branch-triggered
• Locales File Locations:
  • AWS: Copied to origin-request-lambda/handler/supported-countries.json
  • CloudFlare: Available as supportedLocales in proxy and sitemap workers

Development

To contribute or modify the generator:

git clone https://github.com/outliant/generator-webflow-proxy.git
cd generator-webflow-proxy
npm install
npm link

Make your changes and test with yo webflow-proxy in a separate directory.

License

MIT