🌐 CDN Integration Guide (AWS S3 + CloudFront + Vite + Vercel)

Goal: Serve static assets (images, CSS, JS, fonts, etc.) efficiently from AWS S3 + CloudFront while deploying your Vue 3 + Vite app via Vercel.

This setup ensures blazing-fast asset delivery, cache safety, easy rollbacks, and lightweight frontend deployments.

---

🧩 Project Overview

This setup supports three distinct build modes:

Build Type	Description	Use Case
Local Build (npm run build)	Normal Vite build, serves assets locally from /assets/.	Local development.
Timestamped Build (npm run build:ts)	Builds and uploads versioned assets (e.g., /assets/20251004175023/assets/).	Local testing of CDN flow.
Production Build (via GitHub Actions)	Builds timestamped assets, uploads to S3 + CloudFront, and deploys the app to Vercel.	CI/CD deployment for production.

---

⚙️ 1. Local Build Flow (npm run dev or npm run build)

🔹 Purpose

For quick development and testing using your local server.

🔹 Flow

1. The getAssets.js file dynamically imports all images (and subdirectories) from /src/assets/.
2. The Vue app uses Vue’s provide/inject API to make these images globally accessible.

Example:

// getAssets.js
const modules = import.meta.glob('./**/*.@(jpg|png|gif|svg)', { eager: true });
let images = {};

for (const path in modules) {
  const fileName = path.split('/').pop();
  images[fileName] = modules[path].default;
}

export default images;

App setup:

// main.js
import { createApp } from 'vue';
import App from './App.vue';
import images from './assets/getAssets.js';

const app = createApp(App);
app.provide('appImages', images);
app.mount('#app');

In components:

<img :src="appImages['logo.png']" alt="Logo" />

✅ Assets are resolved from local /assets/ folder. ❌ No CDN or AWS involvement.

---

🕒 2. Timestamped Build Flow (npm run build:ts)

🔹 Purpose

To test the CDN flow locally, ensuring that assets are built, uploaded to S3, and linked correctly in the HTML.

🔹 Key Behavior

• Generates a timestamp like 20251004175023

• Builds your app using Vite with that timestamp

• Uploads the built assets to:

  s3://test-cdn-pipeline/assets/<timestamp>/assets/

• Rewrites asset URLs in index.html:

  https://d2ip2t1fu9lfn9.cloudfront.net/assets/<timestamp>/assets/<file>.js

🔹 Environment Requirements

You need a .env.production file locally:

AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
VITE_CDN_URL=https://<your-cloudfront-domain>

🔹 Commands

npm run build:ts

🔹 Under the Hood

build:ts triggers scripts/build-and-upload.js, which:

1. Generates a timestamp.
2. Runs vite build with that timestamp.
3. Uploads the dist/assets folder to S3 under /assets/<timestamp>/assets/.

---

🚀 3. Production Build Flow (CI/CD)

Triggered automatically on push to main branch via GitHub Actions.

🔹 Pipeline Overview

1. build.yml — Builds app and sets BUILD_TIMESTAMP.

2. upload-assets.yml — Uploads assets to:

   • /assets/<timestamp>/assets/ (versioned)
   • /assets/latest/ (for production)
   • Invalidates CloudFront cache.

3. deploy-vercel.yml — Deploys the latest dist folder to Vercel.

🔹 GitHub Secrets Required

Secret Name	Description
AWS_ACCESS_KEY_ID	IAM access key with S3 + CloudFront permissions.
AWS_SECRET_ACCESS_KEY	Secret key for the above.
AWS_REGION	Your AWS region (e.g., eu-north-1).
CLOUDFRONT_DIST_ID	Your CloudFront distribution ID.
VERCEL_TOKEN	Vercel personal access token.
VERCEL_PROJECT_ID	Vercel project ID.
VERCEL_ORG_ID	Vercel organization ID.
VITE_CDN_URL	CloudFront URL (e.g., https://dxxxxx.cloudfront.net).

---

🏧 4. AWS Setup Guide

🪳 S3 Bucket Setup

1. Create an S3 bucket (e.g., test-cdn-pipeline).
2. Disable “Block all public access.”
3. Enable versioning if you want historical rollbacks.
4. Add this bucket policy (replace with your CloudFront distribution ID):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowCloudFrontServicePrincipal",
      "Effect": "Allow",
      "Principal": { "Service": "cloudfront.amazonaws.com" },
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::test-cdn-pipeline/*",
      "Condition": {
        "StringEquals": {
          "AWS:SourceArn": "arn:aws:cloudfront::<YOUR_AWS_ACCOUNT_ID>:distribution/<YOUR_DIST_ID>"
        }
      }
    }
  ]
}

---

🌍 CloudFront Setup

1. Origin Domain: your S3 bucket (e.g., test-cdn-pipeline.s3.eu-north-1.amazonaws.com)

2. Origin Access Control (OAC):

   • Create a new OAC and attach it to your S3 bucket.

3. Viewer Protocol Policy: Redirect HTTP → HTTPS

4. Cache Policy: Managed-CachingOptimized

5. Origin Request Policy: Managed-CORS-With-Preflight

6. Response Header Policy: none (optional)

---

⏳ Lifecycle Rules

In your S3 bucket → Management → Lifecycle Rules, add:

• Rule name: delete-old-asset-versions
• Prefix: assets/
• Action: Delete objects older than 1 day
• Filter: Include all objects
• Enabled: ✅ Yes

This keeps the bucket clean by auto-deleting old timestamped folders, leaving only recent ones.

---

🗁 File Reference Overview

File	Purpose
vite.config.js	Handles asset URL rewriting to CDN.
scripts/deploy-cdn.js	Uploads built files to S3 and rewrites HTML.
scripts/build-and-upload.js	Generates timestamp, builds app, and calls deploy script.
.github/workflows/build.yml	Automates full CI/CD build, upload, and deploy.
.github/workflows/upload-assets.yml	Uploads assets and invalidates cache.
.github/workflows/deploy-vercel.yml	Deploys built app to Vercel.

---

🧠 Rollback Strategy

Each build is stored under /assets/<timestamp>/assets/. To roll back:

1. Find your previous timestamp folder in S3.

2. Replace latest with that version manually:

   aws s3 sync s3://test-cdn-pipeline/assets/20251004175023/assets/ s3://test-cdn-pipeline/assets/latest/assets/ --delete

3. Invalidate CloudFront cache.

---

🗳 Summary

Feature	Local	Timestamp	Production
Assets Location	/assets/	/assets/<timestamp>/assets/	/assets/latest/
CDN Used	❌	✅	✅
Upload to S3	❌	✅	✅
CloudFront Invalidation	❌	❌	✅
Auto Cleanup	❌	✅ via Lifecycle	✅ via Lifecycle
Deployment	Local	Local Test	Vercel CI/CD

---

🧪 Pro Tips

• Use timestamped builds for internal QA / preview environments.

• Always keep the latest folder synced for production.

• If a file gets 403 (Access Denied), double-check:

  • S3 policy matches CloudFront OAC ARN.
  • CloudFront cache is invalidated.
  • The bucket region and distribution are correctly configured.

---

❤️ Credits

Created for a scalable Vite + Vue + AWS + Vercel CDN pipeline by Altersquare