2026-03-09 - Microfrontend Deployment Guide to AWS

Microfrontend Deployment Guide to AWS

Table of Contents

1. Build Process
2. Deploying Individual Microfrontends
3. RootConfig Deployment
4. CloudFront Configuration for RootConfig
5. Deployment Checklist
6. Troubleshooting

---

Build Process

Building a Microfrontend

Each microfrontend project contains a build script in package.json:

package.json file in mfe

To build the microfrontend, run:

npm run build

This command will create a dist folder containing the compiled assets:

output file when build

Uploading to S3

After building, upload the contents of the dist folder to your S3 bucket:

Note|Upload only the contents of the dist folder, not the folder itself.

S3 Bucket Configuration

CORS Configuration

Configure CORS (Cross-Origin Resource Sharing) on your S3 bucket to allow CloudFront and browsers to access the files:

[
    {
        "AllowedHeaders": [],
        "AllowedMethods": [
            "GET",
            "PUT",
            "POST",
            "DELETE"
        ],
        "AllowedOrigins": [
            "*"
        ],
        "ExposeHeaders": []
    }
]

To configure CORS:

1. Go to AWS S3 Console
2. Select your bucket
3. Navigate to Permissions > CORS
4. Paste the JSON configuration above
5. Save changes

Bucket Policy

Configure bucket permissions to allow CloudFront to access the S3 objects.

Option 1: Restrict to Specific CloudFront Distributions (Recommended)

{
    "Version": "2008-10-17",
    "Id": "PolicyForCloudFrontPrivateContent",
    "Statement": [
        {
            "Sid": "AllowCloudFrontServicePrincipal",
            "Effect": "Allow",
            "Principal": {
                "Service": "cloudfront.amazonaws.com"
            },
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::{bucketName}/*",
            "Condition": {
                "ArnLike": {
                    "AWS:SourceArn": [
                        "arn:aws:cloudfront::{accountId}:distribution/E3PN5E1PT6G23P",
                        "arn:aws:cloudfront::{accountId}:distribution/E2Y6DGLLYQFVWW"
                    ]
                }
            }
        }
    ]
}

Replace:

• {bucketName} with your actual S3 bucket name
• {accountId} with your AWS account ID
• Distribution IDs with your actual CloudFront distribution IDs

Option 2: Allow Public Read Access

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowPublicReadAccess",
            "Effect": "Allow",
            "Principal": "*",
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::{bucketName}/*"
        }
    ]
}

Replace:

• {bucketName} with your actual S3 bucket name

Important|Option 1 is more secure as it restricts access to specific CloudFront distributions only.

---

Deploying Individual Microfrontends

Each microfrontend needs its own CloudFront distribution for global content delivery.

Step 1: General Settings

Configure the CloudFront distribution with the following general settings:

cloudfront general setting of mfe

Key Points:

• Set a descriptive name for the distribution
• Enable IPv6 if required
• Choose appropriate price class based on your target regions

Step 2: Origin Settings

Configure the S3 bucket as the origin:

cloudfront origin setting of mfe

Configuration:

• Origin Domain: Select your S3 bucket
• Origin Path: Leave empty or specify the microfrontend folder path
• Origin Access: Use Origin Access Control (OAC) for security
• Enable Origin Shield: Optional, for better caching

Step 3: Behaviors Settings

Configure caching behavior:

cloudfront behaviors setting of mfe

Configuration:

• Path Pattern: Default (*)
• Viewer Protocol Policy: Redirect HTTP to HTTPS
• Allowed HTTP Methods: GET, HEAD, OPTIONS
• Cache Policy: CachingOptimized or custom
• Origin Request Policy: Configure as needed
• Response Headers Policy: Add CORS headers if required

---

RootConfig Deployment

The RootConfig serves as the main entry point and orchestrates all microfrontends.

Import Configuration

Local Development Import

For local development, use local imports:

rootconfig import local

Example:

"@org/microfrontend-name": "http://localhost:8080/org-microfrontend-name.js"

Production Deployment Import

For production, use CloudFront URLs:

rootconfig import deployment

Example:

"@org/microfrontend-name": "https://d123456789.cloudfront.net/org-microfrontend-name.js"

Content Security Policy (CSP)

Add Content-Security-Policy meta tag to the index.ejs file:

rootconfig import csp

Example:

<meta http-equiv="Content-Security-Policy"
      content="default-src 'self';
               script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net *.cloudfront.net *.amazonaws.com;
               style-src 'self' 'unsafe-inline';
               connect-src 'self' *.amazonaws.com;">

ImportMap File in S3

The import map defines module resolution for all microfrontends:

rootconfig importmap

Structure:

{
  "imports": {
    "@org/root-config": "https://d123456789.cloudfront.net/org-root-config.js",
    "@org/microfrontend-1": "https://d123456789.cloudfront.net/org-microfrontend-1.js",
    "@org/microfrontend-2": "https://d123456789.cloudfront.net/org-microfrontend-2.js",
    "react": "https://cdn.jsdelivr.net/npm/react@17/umd/react.production.min.js",
    "react-dom": "https://cdn.jsdelivr.net/npm/react-dom@17/umd/react-dom.production.min.js"
  }
}

Upload this file to S3:

aws s3 cp importmap.json s3://izarafrontend/importmap.json --content-type "application/json"

---

CloudFront Configuration for RootConfig

Step 1: General Configuration

cloudfront general setting of root config

Key Configuration:

• Default Root Object: index.html
• Description: Descriptive name for the distribution
• Enable IPv6: Yes (recommended)
• Price Class: Choose based on regions

Step 2: Origins Configuration

cloudfront origin setting of root config

Configuration:

• Origin Domain: Select RootConfig S3 bucket
• Origin Access: Use Origin Access Control (OAC)
• Origin Shield: Optional
• Ensure S3 bucket policy allows CloudFront access

Step 3: Behaviors Configuration

cloudfront behaviors setting of root config

Configuration:

• Path Pattern: Default (*)
• Viewer Protocol Policy: Redirect HTTP to HTTPS
• Allowed HTTP Methods: GET, HEAD, OPTIONS
• Cache Policy: CachingOptimized
• Origin Request Policy: CORS-CustomOrigin or custom
• Response Headers Policy: SimpleCORS

Step 4: Error Pages Configuration

Configure custom error responses for SPA routing:

cloudfront errorPages setting of root config

Required Error Page:

• HTTP Error Code: 403 (Forbidden) and 404 (Not Found)
• Customize Error Response: Yes
• Response Page Path: /index.html
• HTTP Response Code: 200 (OK)
• Error Caching Minimum TTL: 300 seconds

Important|This configuration ensures that client-side routing works correctly and handles redirects during login/logout flows.

---

Deployment Checklist

For Each Microfrontend

• ☐ Create S3 bucket (if not exists)
• ☐ Configure S3 bucket CORS policy
• ☐ Run npm run build
• ☐ Upload dist folder contents to S3
• ☐ Create CloudFront distribution
• ☐ Configure Origin (S3 bucket)
• ☐ Configure Behaviors (caching, HTTPS)
• ☐ Update S3 bucket policy to allow CloudFront access
• ☐ Note the CloudFront URL

For RootConfig

• ☐ Create S3 bucket for RootConfig (if not exists)
• ☐ Configure S3 bucket CORS policy
• ☐ Update import map with production URLs
• ☐ Add Content-Security-Policy meta tag
• ☐ Upload import map to S3
• ☐ Run npm run build
• ☐ Upload dist folder contents to S3
• ☐ Create CloudFront distribution with index.html as default root object
• ☐ Configure error pages (403/404 → 200)
• ☐ Update S3 bucket policy to allow CloudFront access
• ☐ Test all microfrontends load correctly

Post-Deployment

• ☐ Test all routes work correctly
• ☐ Verify login/logout redirects
• ☐ Check console for CSP violations
• ☐ Test on different browsers
• ☐ Verify HTTPS is enforced

---

Troubleshooting

Issue: Microfrontend not loading

Solution:

• Check CloudFront URL in import map
• Verify S3 bucket permissions
• Check CORS configuration
• Inspect browser console for errors

Issue: 403/404 errors on page refresh

Solution:

• Configure CloudFront error pages to redirect to index.html with 200 response code

Issue: CSP violations

Solution:

• Update Content-Security-Policy meta tag to allow required domains
• Check browser console for specific violations

Issue: Module not found errors

Solution:

• Verify import map JSON is valid
• Check that all microfrontend URLs are correct
• Ensure import map is accessible (CORS, permissions)

Issue: CORS errors or Access Denied

Solution:

• Verify S3 bucket CORS configuration is set correctly
• Check S3 bucket policy allows CloudFront access
• Ensure CloudFront distribution ARN is included in bucket policy
• Verify CloudFront Origin Access Control (OAC) is configured
• Check that S3 bucket is not blocking public access if using public policy
• Clear CloudFront cache after policy changes

---

Additional Resources

• Single-SPA Documentation
• AWS CloudFront Documentation
• SystemJS Import Maps

---