static-aws-deploy

A production-ready CLI tool to deploy static frontend builds (React, Vite, Next.js, Vue, etc.) to AWS S3 and optionally invalidate CloudFront distributions with smart cache-control headers.

🚀 Features

• Zero Configuration Deployment: One command to build and deploy.
• Smart Caching: Automatically applies optimal Cache-Control headers based on file types.
• CloudFront Invalidation: Automatic invalidation of specific paths (default: /index.html).
• Local Credentials Support: Securely use AWS access keys directly in your config.
• Automatic Script Setup: Injects deployment scripts into your package.json.
• Cross-Platform: Works seamlessly on Windows, macOS, and Linux.

📦 Installation

Install globally via npm:

npm install -g static-aws-deploy

Or run directly using npx:

npx static-aws-deploy deploy

🛠 Quick Start

Step 1: Initialize

Run the following command in your project root:

static-aws-deploy init

This creates a static-aws-deploy.config.json file and adds a "deploy:aws" script to your package.json.

Step 2: Configure

Edit static-aws-deploy.config.json with your AWS details:

{
  "bucket": "your-s3-bucket-name",
  "region": "us-east-1",
  "buildCommand": "npm run build",
  "buildDir": "dist",
  "cloudfrontDistributionId": "E123456789ABCD",
  "invalidate": true,
  "invalidationPaths": ["/index.html"],
  "accessKeyId": "AKIA...",
  "secretAccessKey": "..."
}

Step 3: Deploy

Deploy your application with a single command:

npm run deploy:aws

🧠 Cache Control Strategy

The tool automatically applies the following headers to your S3 objects:

| File Type | Cache-Control Header | | :--- | :--- | | index.html | no-cache | | .js, .css | public, max-age=31536000, immutable | | Images (.jpg, .png, .svg, etc.) | public, max-age=86400 | | Others | public, max-age=3600 |

🔐 AWS IAM Permissions

Ensure your AWS credentials have the following minimum permissions:

Example IAM Policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::your-bucket-name",
        "arn:aws:s3:::your-bucket-name/*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": ["cloudfront:CreateInvalidation"],
      "Resource": "arn:aws:cloudfront::YOUR_ACCOUNT_ID:distribution/YOUR_DISTRIBUTION_ID"
    }
  ]
}

❗ Important Security Note

Never commit your static-aws-deploy.config.json to a public repository if it contains your accessKeyId and secretAccessKey.

Add it to your .gitignore:

static-aws-deploy.config.json

📄 License

MIT