scf-deploy
v3.0.2
Published
S3 + CloudFront static deployment automation CLI with automatic SSL certificate creation
Maintainers
Readme
scf-deploy - S3 + CloudFront Deployment CLI
Automate static website deployment to AWS S3 and CloudFront with a simple, powerful CLI tool.
Current Version: 3.0.0
What's New in v3.0.0: Enhanced security with Origin Access Control (OAC)! S3 buckets are now private and only accessible through CloudFront. CloudFront is always enabled for security - no more
enabledoption needed.
Table of Contents
- Features
- Installation
- Quick Start
- Configuration
- Automatic SSL Certificate Creation
- Commands
- AWS Credentials
- Features in Detail
- Examples
- Troubleshooting
- Requirements
- Best Practices
- Testing
- Contributing
Features
🚀 Deployment & Build
- Simple Deployment: Deploy with a single command
npx scf-deploy deploy - Auto Build: Automatically builds your project before deployment
- Auto Build Detection: Automatically finds your build directory (dist, build, out, etc.)
- Build Validation: Ensures deployable files exist before creating AWS resources
- SSR Detection: Prevents accidental deployment of SSR builds (.next, .nuxt)
- Incremental Deployment: Only upload changed files (SHA-256 hash comparison)
⚙️ Configuration & Setup
- Easy Setup: Interactive
initcommand with guided configuration - TypeScript Configuration: Type-safe config files with full IDE support
- Multi-Environment Support: Manage dev, staging, and prod environments
- AWS Credentials Integration: Supports AWS profiles, environment variables, and IAM roles
🔐 SSL & Custom Domains (NEW in v0.5.0)
- Automatic SSL Certificate Creation: Just provide your domain name - SSL certificate is created automatically
- Route53 Hosted Zone Auto-Creation: Automatically creates hosted zones if they don't exist
- DNS Alias Records: Automatic A/AAAA alias record creation for CloudFront distributions
- Route53 Integration: Automatic DNS validation record creation
- Certificate Reuse: Automatically detects and reuses existing certificates
- Zero Configuration HTTPS: No need to manually create ACM certificates or hosted zones
- Domain Ownership Verification: Validates Route53 hosted zone before deployment
☁️ CloudFront & Performance
- CloudFront Integration: Automatic cache invalidation after deployment
- SPA Mode (Default): Automatic 403/404 → index.html redirect for client-side routing
- Cache Warming: Pre-warm edge locations to eliminate cold start latency
- Custom Domains: Built-in support for custom domains with automatic SSL
- CDN Optimization: Configurable price classes with CachingOptimized policy
- Free Tier Compatible: Uses AWS Managed Cache Policy for CloudFront Free tier pricing plan eligibility
📦 State & Resource Management (Enhanced in v0.5.0)
- State Management: Track deployed resources locally with automatic .gitignore handling
- Enhanced State Recovery: Recover lost state files from AWS resource tags (S3, CloudFront, ACM, Route53)
- Tag-Based Resource Discovery: Find and manage all SCF-managed resources without state files
- Comprehensive Resource Tagging: All AWS resources automatically tagged (
scf:managed,scf:app,scf:environment) - Complete Resource Deletion: Remove command now deletes ACM certificates and Route53 hosted zones
- Resource Tracking: View all deployed resources even without state files
💻 Developer Experience
- Progress Tracking: Real-time upload progress with visual feedback
- Detailed Logging: Clear, colorful output with step-by-step feedback
- Error Handling: Helpful error messages with actionable suggestions
Installation
npm install -g scf-deploynpm install scf-deployDirect Execution with npx (Recommended)
npx scf-deploy deployQuick Start
1. Initialize Configuration
Run the init command to create scf.config.ts:
npx scf-deploy initThis will guide you through an interactive setup or you can use defaults:
npx scf-deploy init --yesOr manually create scf.config.ts in your project root:
import type { SCFConfig } from "scf-deploy";
const config: SCFConfig = {
app: "my-static-site",
region: "ap-northeast-2",
s3: {
bucketName: "my-site-bucket",
// buildDir is auto-detected (dist, build, out, etc.)
// You can override: buildDir: './custom-dir',
indexDocument: "index.html",
errorDocument: "404.html",
},
cloudfront: {
// CloudFront is always enabled for security (OAC restricts S3 access)
// priceClass: 'PriceClass_100', // Optional, defaults to PriceClass_100
},
};
export default config;Benefits of type annotation:
- ✅ IDE auto-completion: Get suggestions for all available properties
- ✅ Type checking: Catch errors before deployment
- ✅ Documentation: Hover tooltips show property descriptions
- ✅ Validation: Required properties are enforced at compile time
2. Deploy
npx scf-deploy deployThat's it! scf-deploy will:
- ✅ Automatically build your project (runs
npm run buildif available) - ✅ Auto-detect your build directory (dist, build, out, etc.)
- ✅ Validate build output (checks for index.html and web files)
- ✅ Upload to S3 with incremental deployment
- ✅ Deploy to CloudFront and invalidate cache
- ✅ Warm up edge locations (if cache warming is enabled)
Note: You can skip auto-build with --skip-build flag if needed:
npx scf-deploy deploy --skip-buildConfiguration
Basic Configuration
import type { SCFConfig } from "scf-deploy";
const config: SCFConfig = {
app: "my-app", // Application name
region: "us-east-1", // AWS region
s3: {
bucketName: "my-bucket",
// buildDir is optional - auto-detected from: dist, build, out, .output/public, _site
indexDocument: "index.html",
errorDocument: "404.html",
},
cloudfront: {
// CloudFront is always enabled (OAC secures S3 access)
// priceClass: 'PriceClass_100', // Optional: PriceClass_100, PriceClass_200, PriceClass_All
},
};
export default config;Environment Variables
scf-deploy supports environment-specific variables through .env files. This is the recommended way to manage sensitive information like AWS credentials and custom domain certificates.
How It Works
Environment variables are loaded automatically before config file execution:
- Default:
.envand.env.local(no--envflag) - Development:
.env.devand.env.dev.local(use--env dev) - Production:
.env.prodand.env.prod.local(use--env prod)
Loading Priority (highest to lowest):
.env.{environment}.local (e.g., .env.prod.local)
.env.{environment} (e.g., .env.prod)
.env.local
.envSetup
1. Create environment files:
# .env.dev
AWS_REGION=us-east-1
S3_BUCKET_NAME=my-app-bucket-dev
# .env.prod
AWS_REGION=us-east-1
S3_BUCKET_NAME=my-app-bucket-prod
CLOUDFRONT_DOMAIN=www.example.com
ACM_CERTIFICATE_ARN=arn:aws:acm:us-east-1:123456789012:certificate/xxx2. Use in scf.config.ts:
import type { SCFConfig } from "scf-deploy";
const config: SCFConfig = {
app: process.env.APP_NAME || "my-app",
region: process.env.AWS_REGION || "us-east-1",
s3: {
bucketName: process.env.S3_BUCKET_NAME || "my-app-bucket",
indexDocument: "index.html",
},
cloudfront: {
// CloudFront is always enabled for security
customDomain: process.env.CLOUDFRONT_DOMAIN
? {
domainName: process.env.CLOUDFRONT_DOMAIN,
certificateArn: process.env.ACM_CERTIFICATE_ARN,
}
: undefined,
},
};
export default config;3. Deploy with environment:
# Development (loads .env.dev)
scf-deploy deploy --env dev
# Production (loads .env.prod)
scf-deploy deploy --env prodSecurity Best Practices
- ✅ Always add
.env*to.gitignore - ✅ Use
.env.examplefiles to document required variables - ✅ Store sensitive values (AWS keys, certificate ARNs) in
.envfiles - ❌ Never commit actual
.envfiles to git - ✅ Use
.env.localfor local overrides that shouldn't be shared
Example Files
Check your project root for:
.env.example- Template with all available variables.env.dev.example- Development environment template.env.prod.example- Production environment template
Copy these to create your actual .env files:
cp .env.example .env
cp .env.dev.example .env.dev
cp .env.prod.example .env.prodMissing Environment File Warning
If you use --env flag but the corresponding .env file doesn't exist, scf-deploy will show a warning:
$ scf-deploy deploy --env dev
⚠ Warning: .env.dev file not found. Using default values from scf.config.tsThis is just a warning - deployment will continue using the default values defined in scf.config.ts.
Build Directory Auto-Detection
scf-deploy automatically detects your build directory by searching for:
dist- Vite, Rollup, Vue, etc.build- Create React App, Next.js, etc.out- Next.js static export.output/public- Nuxt 3_site- Jekyll, 11tyoutput- Some SSGs
Requirements:
- Directory must contain
index.htmlas the entry point - Must have deployable web files (.html, .js, .css, etc.)
SSR Build Detection: scf-deploy will reject SSR build directories that require a server:
.next- Next.js SSR build.nuxt- Nuxt SSR build
For Next.js, use next export to generate static files in ./out:
# next.config.js
module.exports = {
output: 'export',
};
# Then build
npm run build
# Creates ./out directory with static filesSPA Mode (Single Page Application)
CloudFront is configured with SPA mode enabled by default (spa: true). This automatically redirects 403/404 errors to index.html with a 200 status code, enabling client-side routing for React Router, Vue Router, Angular Router, etc.
import type { SCFConfig } from "scf-deploy";
const config: SCFConfig = {
app: "my-spa-app",
region: "us-east-1",
s3: {
bucketName: "my-spa-bucket",
},
cloudfront: {
// SPA mode is true by default - no configuration needed!
// spa: true, // Redirect 403/404 to index.html (default)
},
};
export default config;How SPA Mode Works:
When spa: true (default):
- 403 errors (Access Denied) →
/index.htmlwith 200 status - 404 errors (Not Found) →
/index.htmlwith 200 status - Client-side routing handles the actual URL
For Static HTML Sites (disable SPA mode):
If you have a traditional static site that needs to show actual 404 error pages:
cloudfront: {
spa: false, // Disable SPA mode - return default 404 errors
}Custom Error Pages (advanced):
For fine-grained control, use errorPages configuration:
cloudfront: {
spa: false, // Disable default SPA behavior
errorPages: [
{ errorCode: 404, responsePath: '/404.html', responseCode: 404, cacheTTL: 300 },
{ errorCode: 403, responsePath: '/403.html', responseCode: 403, cacheTTL: 300 },
],
}CloudFront Pricing Plans (New in Nov 2025)
SCF creates CloudFront distributions using the CachingOptimized managed cache policy, which makes them eligible for AWS's new flat-rate pricing plans:
| Plan | Price | Requests | Data Transfer | |------|-------|----------|---------------| | Free | $0/mo | 1M | 100GB | | Pro | $15/mo | 10M | 50TB | | Business | $200/mo | 125M | 50TB |
Key Benefits of Free Plan:
- ✅ No overage charges (performance throttling instead)
- ✅ Protection from traffic spikes and DDoS attacks
- ✅ Up to 3 Free plans per AWS account
After deployment, SCF displays instructions to switch to the Free plan in the AWS Console.
Note: Pricing plans can only be configured in the AWS Console (not via API/SDK).
Environment-Specific Configuration
import type { SCFConfig } from "scf-deploy";
const config: SCFConfig = {
app: "my-app",
region: "ap-northeast-2",
s3: {
bucketName: "my-site-prod",
},
cloudfront: {
// CloudFront is always enabled for security
},
// Environment overrides
environments: {
dev: {
s3: { bucketName: "my-site-dev" },
},
staging: {
s3: { bucketName: "my-site-staging" },
},
prod: {
cloudfront: { priceClass: "PriceClass_All" }, // Use all edge locations in prod
},
},
};
export default config;Automatic SSL Certificate Creation
NEW in v0.5.0 - Zero-configuration HTTPS for your custom domains!
Simple Configuration (Automatic SSL)
Just provide your domain name - scf-deploy handles the rest:
import type { SCFConfig } from "scf-deploy";
const config: SCFConfig = {
app: "my-app",
region: "us-east-1",
s3: {
bucketName: "my-site",
},
cloudfront: {
customDomain: {
domainName: "example.com", // That's it! SSL certificate is created automatically
},
},
};
export default config;What Happens Automatically
When you deploy with just domainName:
- ✅ Route53 Hosted Zone Check - Checks if hosted zone exists for domain
- ✅ Auto-Create Hosted Zone - Creates hosted zone automatically if not found (NEW!)
- ✅ Certificate Search - Looks for existing valid certificates
- ✅ Certificate Creation - Requests new ACM certificate if needed (in us-east-1)
- ✅ DNS Validation - Creates DNS validation records in Route53
- ✅ Validation Wait - Waits for certificate to be validated (5-30 minutes)
- ✅ CloudFront Setup - Applies certificate to CloudFront distribution
- ✅ DNS Alias Records - Creates A/AAAA alias records pointing to CloudFront (NEW!)
- ✅ HTTPS Ready - Your site is live with HTTPS!
Deployment Output
$ npx scf-deploy deploy --env prod
🔐 Custom domain detected without certificate
Domain: example.com
Starting automatic SSL certificate creation...
✓ Route53 hosted zone found: Z123456789ABC
✓ Existing certificate found: abc-123
Reusing existing certificate
✓ SSL certificate ready for CloudFront
📦 S3 uploading...
☁️ CloudFront deploying...
✓ Deployment complete!
Custom Domain: https://example.comManual Certificate (Optional)
If you already have a certificate or want to manage it manually:
import type { SCFConfig } from "scf-deploy";
const config: SCFConfig = {
app: "my-app",
region: "us-east-1",
s3: {
bucketName: "my-site",
},
cloudfront: {
customDomain: {
domainName: "example.com",
certificateArn: "arn:aws:acm:us-east-1:123456789012:certificate/abc-def", // Use existing certificate
},
},
};
export default config;Requirements for Automatic SSL
- Route53 Hosted Zone: Your domain must be registered in Route53 (or will be created automatically)
- AWS Permissions: ACM and Route53 permissions required (see below)
- Time: First deployment takes 5-30 minutes for certificate validation
- Region: Certificate is automatically created in us-east-1 (CloudFront requirement)
Note: If a hosted zone doesn't exist for your domain, scf-deploy will automatically create one. You'll need to update your domain's nameservers at your registrar to point to the Route53 nameservers (displayed after creation).
Certificate Reuse
scf-deploy automatically detects and reuses existing certificates:
- Subsequent deployments: ~5 seconds (no certificate creation)
- Multiple apps with same domain: Certificate is shared automatically
- Manual certificates: Always respected when
certificateArnis provided
Commands
init
Initialize scf.config.ts configuration file.
# Interactive mode (asks questions)
scf-deploy init
# Non-interactive mode (use defaults)
scf-deploy init --yes
# Use a template (react, vue, next, custom)
scf-deploy init --template react
# Overwrite existing config
scf-deploy init --forceOptions:
-f, --force- Overwrite existing config file-y, --yes- Skip prompts and use default values-t, --template <template>- Use template (custom, react, vue, next)
Templates:
custom- Custom configuration (default build dir:./dist)react- React/CRA configuration (build dir:./build)vue- Vue.js configuration (build dir:./dist)next- Next.js static export (build dir:./out)
deploy
Deploy your static site to S3 and CloudFront.
# Basic deployment
scf-deploy deploy
# Deploy to specific environment
scf-deploy deploy --env prod
# Use specific AWS profile
scf-deploy deploy --profile my-aws-profile
# Preview without uploading
scf-deploy deploy --dry-run
# Force full deployment (ignore cached state)
scf-deploy deploy --forceOptions:
-e, --env <environment>- Environment name (default: "default")-c, --config <path>- Config file path (default: "scf.config.ts")-p, --profile <profile>- AWS profile name--dry-run- Preview deployment without uploading--force- Force full deployment (ignore state)--skip-cache- Skip CloudFront cache invalidation--skip-build- Skip automatic build--no-rollback- Keep S3 bucket if CloudFront deployment fails (NEW in v2.1.0)--no-cleanup- Skip deletion of removed files from S3 (NEW in v2.1.0)
remove
Remove deployed AWS resources (Enhanced in v0.5.0).
# Remove all resources (with confirmation prompt)
scf-deploy remove
# Force remove without confirmation
scf-deploy remove --force
# Remove specific environment
scf-deploy remove --env dev
# Keep S3 bucket (only delete files)
scf-deploy remove --keep-bucket
# Keep CloudFront distribution
scf-deploy remove --keep-distribution
# Keep ACM certificate
scf-deploy remove --keep-certificate
# Keep Route53 hosted zone
scf-deploy remove --keep-hosted-zoneWhat gets deleted:
The remove command will delete ALL resources created by scf-deploy:
- 🗑️ CloudFront Distribution - Distribution is disabled and deleted
- 🗑️ ACM Certificate - SSL certificate is removed (NEW in v0.5.0)
- 🗑️ S3 Bucket - All files and the bucket are deleted
- 🗑️ Route53 Hosted Zone - Hosted zone and all DNS records deleted (NEW in v0.5.0)
Before deletion, you'll see a detailed list of all resources that will be removed.
Tag-Based Discovery (NEW in v0.5.0):
Even without a state file, remove can discover and delete resources using AWS tags:
# Works even if .deploy/state.json is missing!
scf-deploy remove --env prodOptions:
-e, --env <environment>- Environment name (default: "default")-c, --config <path>- Config file path (default: "scf.config.ts")-p, --profile <profile>- AWS profile name-f, --force- Skip confirmation prompt--keep-bucket- Keep S3 bucket (only delete files)--keep-distribution- Keep CloudFront distribution--keep-certificate- Keep ACM certificate (NEW in v0.5.0)--keep-hosted-zone- Keep Route53 hosted zone (NEW in v0.5.0)
Example:
$ scf-deploy remove --env prod
🗑️ SCF Resource Removal
📋 Resources to be removed:
S3 Bucket:
Bucket Name: my-app-prod-abc123
Region: us-east-1
CloudFront Distribution:
Distribution ID: E1234567890ABC
Domain Name: d123456.cloudfront.net
ACM Certificate:
Certificate ARN: arn:aws:acm:us-east-1:...
Domain Name: example.com
Route53 Hosted Zone:
Zone ID: Z1234567890ABC
Zone Name: example.com.
⚠️ Warning: This action cannot be undone!
? Are you sure you want to delete these resources? (y/N)status
Check current deployment status.
# Basic status
scf-deploy status
# Specific environment
scf-deploy status --env prod
# Detailed information
scf-deploy status --detailed
# JSON output
scf-deploy status --jsonOptions:
-e, --env <environment>- Environment name (default: "default")-d, --detailed- Show detailed information--json- Output as JSON
recover
Recover lost deployment state from AWS resources (Enhanced in v0.5.0).
If you accidentally delete the .deploy/state.json file, you can recover it from AWS resource tags.
# Recover state for default environment
scf-deploy recover
# Recover specific environment
scf-deploy recover --env prod
# Show all SCF-managed resources
scf-deploy recover --all
# Overwrite existing state file
scf-deploy recover --forceEnhanced Resource Discovery (NEW in v0.5.0):
Now discovers ALL AWS resources, not just S3 and CloudFront:
- 📦 S3 Buckets - Tagged buckets with app/environment
- ☁️ CloudFront Distributions - Distributions with matching tags
- 🔐 ACM Certificates - SSL certificates with domain info (NEW!)
- 🌐 Route53 Hosted Zones - DNS zones with domain records (NEW!)
How it works:
- Searches for all resources with
scf:managed=truetag - Filters by app name and environment from config
- Discovers S3 buckets, CloudFront distributions, ACM certificates, and Route53 zones
- Reconstructs the complete state file from AWS metadata
Options:
-e, --env <environment>- Environment name to recover-c, --config <path>- Config file path (default: "scf.config.ts")-p, --profile <profile>- AWS profile name-f, --force- Overwrite existing state file-a, --all- Show all SCF-managed resources across all apps/environments (NEW!)
Example with --all flag:
$ scf-deploy recover --all
🔄 SCF State Recovery
All SCF-managed resources:
S3 Buckets:
✓ my-app-prod (app: my-app, env: prod)
✓ my-app-dev (app: my-app, env: dev)
CloudFront Distributions:
✓ E1234567890ABC (app: my-app, env: prod)
Domain: d123456.cloudfront.net
ACM Certificates:
✓ example.com (my-app, prod)
Status: ISSUED
Route53 Hosted Zones:
✓ example.com. (my-app, prod)Automatic Resource Tags:
All AWS resources created by scf-deploy are automatically tagged:
scf:managed=true- Indicates resource is managed by scf-deployscf:app=<app-name>- Application name from configscf:environment=<env>- Environment namescf:tool=scf-deploy- Tool identifier- Resource-specific tags (domain, region, etc.)
AWS Credentials
scf-deploy looks for AWS credentials in the following order:
- Command-line option:
--profileflag - Environment variables:
AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY - AWS CLI profiles:
~/.aws/credentials - IAM Role: When running on EC2, ECS, etc.
Using AWS Profile
scf-deploy deploy --profile my-company-profileUsing Environment Variables
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
scf-deploy deployFeatures in Detail
Build Validation
Before creating any AWS resources, scf-deploy validates your build:
- Auto-detection: Searches for common build directories (dist, build, out, etc.)
- index.html check: Ensures an entry point exists
- Deployable files: Verifies web files (.html, .js, .css, etc.) are present
- SSR rejection: Prevents deployment of SSR builds that require a server
This prevents wasted time and costs by catching issues before AWS resources are created.
Automatic .gitignore Management
scf-deploy automatically manages your .gitignore file:
- Auto-detection: Checks if your project is a Git repository
- Safe addition: Adds
.deploy/if not already present - Non-intrusive: Creates
.gitignoreif it doesn't exist - One-time: Only modifies once, won't duplicate entries
This happens automatically during:
scf-deploy init- When initializing configurationscf-deploy deploy- After first successful deployment
State Recovery (Enhanced in v0.5.0)
If you accidentally delete .deploy/state.json, you can recover it:
scf-deploy recover --env prodHow it works:
- All AWS resources are tagged with
scf:managed,scf:app,scf:environment,scf:tool recovercommand searches for these tagged resources across all AWS services- State file is reconstructed from AWS metadata
- You can continue deploying without recreating resources
What can be recovered (Enhanced in v0.5.0):
- ✅ S3 bucket information (name, region, website URL)
- ✅ CloudFront distribution (ID, domain, ARN)
- ✅ ACM certificate (ARN, domain, status) - NEW!
- ✅ Route53 hosted zone (zone ID, name, nameservers) - NEW!
- ✅ Resource tags and metadata
- ✅ Environment configuration
Note: File hashes are not recoverable, so the next deployment will re-upload all files.
Tag-Based Resource Discovery:
scf-deploy now uses a comprehensive tagging system across all AWS resources:
// Example tags on S3 bucket
{
'scf:managed': 'true',
'scf:app': 'my-app',
'scf:environment': 'prod',
'scf:tool': 'scf-deploy',
'scf:region': 'us-east-1'
}
// Example tags on CloudFront distribution
{
'scf:managed': 'true',
'scf:app': 'my-app',
'scf:environment': 'prod',
'scf:tool': 'scf-deploy'
}
// Example tags on ACM certificate
{
'scf:managed': 'true',
'scf:app': 'my-app',
'scf:environment': 'prod',
'scf:tool': 'scf-deploy',
'scf:domain': 'example.com',
'scf:auto-created': 'true' // If created automatically
}
// Example tags on Route53 hosted zone
{
'scf:managed': 'true',
'scf:app': 'my-app',
'scf:environment': 'prod',
'scf:tool': 'scf-deploy',
'scf:domain': 'example.com'
}This comprehensive tagging enables:
- 🔍 Resource Discovery - Find all resources without state files
- 🗑️ Complete Deletion - Remove command finds all related resources
- 📊 Cost Tracking - Filter AWS costs by
scf:apporscf:environment - 🛡️ Safety - Prevent accidental deletion of non-SCF resources
Incremental Deployment
scf-deploy uses SHA-256 hashing to detect file changes:
- First deployment: All files are uploaded
- Subsequent deployments: Only changed files are uploaded
- Time savings: 80-95% faster deployment times
State is stored in .deploy/state.{env}.json (automatically added to .gitignore).
CloudFront Cache Invalidation
After deployment, scf-deploy automatically:
- Creates or updates CloudFront distribution
- Invalidates cache for changed files
- Waits for distribution to be fully deployed
- Shows real-time progress
CloudFront Cache Warming
Reduce cold start latency by pre-warming CloudFront edge locations after deployment:
import type { SCFConfig } from "scf-deploy";
const config: SCFConfig = {
// ... other config
cloudfront: {
enabled: true,
cacheWarming: {
enabled: true,
paths: ["/", "/index.html", "/app.js"], // Critical paths only
concurrency: 3, // Concurrent requests (max: 10)
delay: 500, // Delay between requests (ms)
},
},
};
export default config;How it works:
- After CloudFront deployment completes, scf-deploy makes HTTP requests to specified paths
- Files are downloaded and cached at edge locations
- First users get cached responses immediately (no cold start)
Cost considerations:
- ⚠️ Data transfer costs: Downloads files, incurs CloudFront outbound traffic charges
- Example: 10 files × 100KB each × $0.085/GB = ~$0.00009 per deployment
- Best practice: Only warm essential files (HTML, critical JS/CSS)
- Avoid: Large images, videos, or non-critical assets
When to use:
- ✅ Production deployments where first-load performance is critical
- ✅ After major releases to ensure global availability
- ❌ Development/staging environments (disable to save costs)
- ❌ High-frequency deployments (costs accumulate)
Configuration tips:
import type { SCFConfig } from "scf-deploy";
const config: SCFConfig = {
app: "my-app",
region: "us-east-1",
s3: {
bucketName: "my-app-bucket",
},
cloudfront: {
enabled: true,
},
environments: {
dev: {
cloudfront: {
enabled: false, // No CloudFront = no warming needed
},
},
staging: {
cloudfront: {
enabled: true,
cacheWarming: { enabled: false }, // Skip warming in staging
},
},
prod: {
cloudfront: {
cacheWarming: {
enabled: true,
paths: ["/", "/index.html"], // Minimal paths
concurrency: 3,
delay: 500,
},
},
},
},
};
export default config;Multi-Environment Support
Manage multiple environments with ease:
scf-deploy deploy --env dev
scf-deploy deploy --env staging
scf-deploy deploy --env prodEach environment:
- Has its own state file
- Can override configuration
- Is completely isolated
Progress Tracking
Visual feedback during deployment:
- File scanning progress
- Upload progress bar
- Real-time status updates
- Detailed error messages
Examples
React Application
# Build your React app
npm run build
# Deploy to production
scf-deploy deploy --env prodConfiguration:
import type { SCFConfig } from "scf-deploy";
const config: SCFConfig = {
app: "my-react-app",
region: "us-east-1",
s3: {
bucketName: "my-react-app",
// buildDir auto-detected (React uses ./build by default)
indexDocument: "index.html",
},
cloudfront: {
// CloudFront always enabled for security
},
};
export default config;Vue Application with Custom Domain
# Build your Vue app
npm run build
# Deploy with automatic SSL
scf-deploy deploy --env prodConfiguration:
import type { SCFConfig } from "scf-deploy";
const config: SCFConfig = {
app: "my-vue-app",
region: "eu-west-1",
s3: {
bucketName: "my-vue-app",
// buildDir auto-detected (Vue uses ./dist by default)
indexDocument: "index.html",
},
cloudfront: {
customDomain: {
domainName: "myapp.com", // SSL certificate created automatically!
},
},
};
export default config;Static HTML Site
import type { SCFConfig } from "scf-deploy";
const config: SCFConfig = {
app: "my-website",
region: "ap-northeast-2",
s3: {
bucketName: "my-website",
// For custom build directory (not auto-detected)
buildDir: "./public",
indexDocument: "index.html",
errorDocument: "404.html",
},
cloudfront: {
spa: false, // Disable SPA mode - show actual 404 pages for missing URLs
},
};
export default config;Production Site with Full Configuration
import type { SCFConfig } from "scf-deploy";
const config: SCFConfig = {
app: "production-app",
region: "us-east-1",
s3: {
bucketName: "production-app-site",
indexDocument: "index.html",
errorDocument: "404.html",
},
cloudfront: {
priceClass: "PriceClass_All", // Global coverage
customDomain: {
domainName: "www.example.com",
// Certificate created automatically (requires Route53)
},
cacheWarming: {
enabled: true,
paths: ["/", "/index.html"],
concurrency: 5,
delay: 300,
},
},
environments: {
staging: {
s3: { bucketName: "staging-app-site" },
cloudfront: {
priceClass: "PriceClass_100",
customDomain: {
domainName: "staging.example.com",
},
cacheWarming: { enabled: false },
},
},
},
};
export default config;Troubleshooting
Command not found
# Check if installed
which scf-deploy
# Reinstall globally
npm uninstall -g scf-deploy
npm install -g scf-deploy
# Or use npx (recommended)
npx scf-deploy deployAWS Credentials Error
# Verify AWS credentials
aws sts get-caller-identity
# Use specific profile
scf-deploy deploy --profile my-profileConfig file not found
# Check if scf.config.ts exists
ls -la scf.config.ts
# Specify custom path
scf-deploy deploy --config ./config/scf.config.tsState file conflicts
# Check state files
ls -la .deploy/
# Force full redeployment
scf-deploy deploy --forceBuild directory not found
# Error: Could not find build directory
# Solution: Ensure you've built your project first
npm run build
# Or specify a custom build directory
# In scf.config.ts:
s3: {
bucketName: 'my-bucket',
buildDir: './my-custom-output',
}SSR build detected error
# Error: Cannot deploy SSR build directory (.next, .nuxt)
# For Next.js: Enable static export
# next.config.js:
module.exports = {
output: 'export', // Generates static files in ./out
};
# For Nuxt: Use static generation
# nuxt.config.js:
export default {
ssr: false, // SPA mode
target: 'static',
};Lost state file recovery
# If you accidentally deleted .deploy/state.json
scf-deploy recover --env prod
# Then continue deploying as normal
scf-deploy deploy --env prodRoute53 Hosted Zone Not Found
NEW in v0.5.0: Hosted zones are now created automatically!
# scf-deploy now automatically creates hosted zones if they don't exist
$ scf-deploy deploy --env prod
⚠ Route53 hosted zone not found for example.com
Creating public hosted zone automatically...
✓ Hosted zone created: Z123456789ABC
Name servers (update at your domain registrar):
- ns-123.awsdns-12.com
- ns-456.awsdns-45.net
- ns-789.awsdns-78.org
- ns-012.awsdns-01.co.ukAfter automatic creation:
- Copy the nameservers displayed in the output
- Log into your domain registrar (GoDaddy, Namecheap, etc.)
- Update your domain's nameservers to the Route53 nameservers
- Wait for DNS propagation (5 minutes to 48 hours)
- Retry deployment - certificate validation will complete once DNS propagates
Manual hosted zone creation (if preferred):
# 1. Go to AWS Route53 Console
# 2. Create hosted zone for your domain
# 3. Update domain nameservers to Route53 nameservers
# 4. Deploy with scf-deploy
# Or use manual certificate:
cloudfront: {
customDomain: {
domainName: "example.com",
certificateArn: "arn:aws:acm:us-east-1:123456789012:certificate/abc-def",
},
}Certificate Validation Timeout
# Error: Certificate validation timed out after 30 minutes
# Possible causes:
# 1. DNS records not propagated yet
# 2. Incorrect Route53 configuration
# 3. Domain nameservers not pointing to Route53
# Solution:
# 1. Check DNS validation records in Route53
# 2. Verify domain nameservers: dig NS example.com
# 3. Wait for DNS propagation (up to 48 hours)
# 4. Retry deployment: scf-deploy deploy --env prodACM or Route53 Permission Denied
# Error: AccessDenied - route53:ChangeResourceRecordSets
# Solution: Add required permissions to your IAM user/role
# Required permissions for automatic SSL:
# - acm:RequestCertificate
# - acm:DescribeCertificate
# - acm:ListCertificates
# - route53:ListHostedZones
# - route53:ChangeResourceRecordSetsRequirements
- Node.js: >= 18.0.0
- AWS Account: With appropriate permissions
- AWS Credentials: Configured via CLI, environment, or IAM role
Required AWS Permissions
Basic Deployment (S3 + CloudFront)
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:CreateBucket",
"s3:DeleteBucket",
"s3:ListBucket",
"s3:PutObject",
"s3:GetObject",
"s3:DeleteObject",
"s3:PutBucketWebsite",
"s3:PutBucketTagging",
"s3:GetBucketTagging",
"s3:ListAllMyBuckets",
"cloudfront:CreateDistribution",
"cloudfront:GetDistribution",
"cloudfront:UpdateDistribution",
"cloudfront:DeleteDistribution",
"cloudfront:CreateInvalidation",
"cloudfront:ListDistributions",
"cloudfront:TagResource",
"cloudfront:ListTagsForResource"
],
"Resource": "*"
}
]
}Additional Permissions for Automatic SSL (NEW in v0.5.0)
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"acm:RequestCertificate",
"acm:DescribeCertificate",
"acm:ListCertificates",
"acm:DeleteCertificate",
"acm:ListTagsForCertificate",
"route53:ListHostedZones",
"route53:GetHostedZone",
"route53:CreateHostedZone",
"route53:DeleteHostedZone",
"route53:ChangeResourceRecordSets",
"route53:ListResourceRecordSets",
"route53:GetChange",
"route53:ChangeTagsForResource",
"route53:ListTagsForResource"
],
"Resource": "*"
}
]
}Enhanced Permissions Explained (v0.5.0):
acm:DeleteCertificate- Forremovecommand to delete certificatesacm:ListTagsForCertificate- For resource discovery and recoveryroute53:CreateHostedZone- For automatic hosted zone creationroute53:DeleteHostedZone- Forremovecommand to delete zonesroute53:ListResourceRecordSets- For DNS record managementroute53:ChangeTagsForResource- For tagging hosted zonesroute53:ListTagsForResource- For resource discoveryroute53:GetHostedZone- For nameserver retrieval
Note: Tagging permissions are required for the enhanced state recovery and resource discovery features.
Best Practices
Leverage auto-build: scf-deploy automatically builds your project
# Auto-build is enabled by default npx scf-deploy deploy # Or manually build first if you prefer npm run build && npx scf-deploy deploy --skip-buildState file management:
.deploy/is automatically added to.gitignore- Never commit state files to Git
- Use
scf-deploy recoverif state is lost
Use environment-specific configs: Separate dev/staging/prod
scf-deploy deploy --env dev # For development scf-deploy deploy --env prod # For productionTest with
--dry-runfirst: Preview changes before deployingscf-deploy deploy --dry-runUse IAM roles in CI/CD: Don't hardcode credentials
- Prefer IAM roles over access keys
- Use AWS profiles locally
- Let EC2/ECS IAM roles work automatically
CloudFront is always enabled: Better security, performance and HTTPS
- CloudFront is required for secure S3 access via OAC
- Use
PriceClass_100for cost optimization - Upgrade to
PriceClass_Allfor global coverage
Use automatic SSL for custom domains (NEW in v0.5.0):
- Just provide
domainName- certificate is created automatically - Requires Route53 hosted zone for your domain
- First deployment takes 5-30 minutes for certificate validation
- Subsequent deployments: instant (certificate is reused)
cloudfront: { customDomain: { domainName: "example.com", // SSL handled automatically! }, }- Just provide
Static export for Next.js: Use
output: 'export'// next.config.js module.exports = { output: "export", };Monitor AWS costs:
- Check S3 storage and transfer costs
- Monitor CloudFront data transfer
- Use CloudWatch for usage metrics
- ACM certificates are free (no additional cost)
Keep your CLI updated:
npm update -g scf-deploy # Or with npx (always uses latest) npx scf-deploy@latest deploy
Git Hooks (Husky)
SCF uses Husky to ensure code quality at different stages of development.
Pre-Commit Checks
When you commit, the following check runs automatically:
git commit -m "your message"This will run:
- 🔍 Lint Check - Ensures code follows style guidelines
Pre-Push Checks
When you push, comprehensive checks run automatically:
git push origin mainThis will run:
- 📦 Build Check - Ensures the project builds without errors
- 🔍 Lint Check - Ensures code follows style guidelines
- 🧪 Unit Tests - Runs all 256 unit tests
- 🔗 Integration Tests - Runs all 104 integration tests
If any check fails, the push will be blocked. You must fix the issues before pushing.
Manual Check
You can run the checks manually:
# Pre-commit check
.husky/pre-commit
# Pre-push check
.husky/pre-pushBypassing Checks (Not Recommended)
In emergency situations, you can bypass the checks:
git commit --no-verify -m "message"
git push --no-verify⚠️ Warning: Only use this in emergencies! It's better to fix the issues.
Testing
SCF uses Jest as the testing framework with comprehensive test coverage across unit, integration, and E2E tests.
Running Tests
# Run all tests
npm test
# Run only unit tests (256 tests)
npm run test:unit
# Run integration tests (104 tests)
npm run test:integration
# Run E2E tests (requires AWS credentials)
npm run test:e2e
# Run tests in watch mode
npm run test:watch
# Run tests with coverage report
npm run test:coverageTest Structure
src/__tests__/
├── unit/ # Unit tests for core modules (256 tests)
│ ├── aws/ # ACM, Route53, CloudFront, S3 managers
│ ├── config/ # Config parsing, validation, merging
│ ├── deployer/ # File scanning, hashing
│ └── state/ # State management
├── integration/ # Integration tests (104 tests)
│ ├── aws/ # AWS service integration tests
│ ├── config/ # Config loading integration
│ └── deployer/ # Deployment workflow tests
├── e2e/ # End-to-end tests (real AWS resources)
│ ├── s3.e2e.test.ts
│ ├── cloudfront.e2e.test.ts
│ ├── acm.e2e.test.ts
│ └── route53.e2e.test.ts
└── fixtures/ # Test data and config filesTest Types
| Type | Count | Description | | ---- | ----- | ----------- | | Unit Tests | 256 | Fast, isolated tests with mocked dependencies | | Integration Tests | 104 | Tests for module interactions with mocked AWS | | E2E Tests | Variable | Real AWS resource tests (requires credentials) | | Total | 360+ | Comprehensive test coverage |
Test Coverage
Current test coverage for core modules:
| Module | Coverage | | --------------- | -------- | | Config Schema | 100% | | Config Merger | 100% | | Config Loader | 91.66% | | File Scanner | 100% | | State Manager | 93.1% | | ACM Manager | 85% | | Route53 Manager | 88% |
Writing Tests
When contributing, please ensure:
- Add tests for new features: All new functionality should include tests
- Maintain coverage: Keep coverage above 90% for core modules
- Use fixtures: Add test data to
src/__tests__/fixtures/ - Follow patterns: Match existing test structure and naming
Example test:
import { describe, it, expect } from "@jest/globals";
import { validateConfig } from "../../../core/config/schema.js";
describe("Config Validation", () => {
it("should validate a minimal config", () => {
const config = {
app: "test-app",
region: "us-east-1",
s3: { bucketName: "test-bucket", buildDir: "./dist" },
};
expect(() => validateConfig(config)).not.toThrow();
});
});Test Scripts
test- Run all teststest:unit- Run only unit teststest:watch- Run tests in watch modetest:coverage- Generate coverage report (saved tocoverage/)
Coverage reports are generated in:
- HTML:
coverage/index.html(open in browser) - LCOV:
coverage/lcov-report/(for CI/CD tools)
CI/CD (GitHub Actions)
SCF uses GitHub Actions for automated testing on every PR and merge.
PR Workflow
When a Pull Request is created or updated:
# .github/workflows/pr.yml
- Build project
- Run linter
- Run unit tests (256 tests)
- Run integration tests (104 tests)Main Branch Workflow
When code is merged to main:
# .github/workflows/main.yml
- Build project
- Run linter
- Run unit tests
- Run integration tests
- Run E2E tests (real AWS resources)Setting Up GitHub Secrets
For E2E tests to run in GitHub Actions, you need to configure AWS credentials:
- Go to your repository Settings > Secrets and variables > Actions
- Add the following secrets:
| Secret Name | Description |
| ----------- | ----------- |
| AWS_ACCESS_KEY_ID | AWS access key with required permissions |
| AWS_SECRET_ACCESS_KEY | AWS secret access key |
Required IAM Permissions for E2E Tests:
- S3: CreateBucket, DeleteBucket, PutObject, GetObject, DeleteObject
- CloudFront: CreateDistribution, GetDistribution, DeleteDistribution
- ACM: RequestCertificate, DescribeCertificate, DeleteCertificate
- Route53: CreateHostedZone, DeleteHostedZone, ChangeResourceRecordSets
Local vs CI Testing
| Environment | Unit | Integration | E2E | | ----------- | ---- | ----------- | --- | | Pre-commit (local) | - | - | - | | Pre-push (local) | ✅ | ✅ | - | | PR (GitHub) | ✅ | ✅ | - | | Main merge (GitHub) | ✅ | ✅ | ✅ |
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
License
MIT License - see LICENSE file for details
Changelog
v3.0.0
🔐 Enhanced Security with Origin Access Control (OAC)
Breaking Changes:
- ⚠️
cloudfront.enabledremoved: CloudFront is now always enabled for security - S3 buckets are private and only accessible via CloudFront - ⚠️
s3.websiteHostingremoved: S3 static website hosting is no longer used - ⚠️ S3 direct access removed: S3 bucket URLs no longer work - use CloudFront URL instead
Added:
- ✨ Origin Access Control (OAC): Secure S3 access through CloudFront only
- ✨ CloudFront Function: Automatic index.html routing for directory requests
- ✨ Enhanced Security: S3 bucket policy restricts access to CloudFront OAC only
Migration Guide (v2.x → v3.0.0):
// Before (v2.x)
cloudfront: {
enabled: true, // ❌ Remove this
priceClass: 'PriceClass_100',
}
// After (v3.0.0)
cloudfront: {
// enabled option no longer exists - CloudFront is always active
priceClass: 'PriceClass_100',
}If you were using S3 bucket URLs directly, switch to CloudFront URLs.
v3.0.1
🔧 S3 Bucket Policy Migration Fix
- 🐛 Fixed: S3 bucket policy now applies on every deployment (not just new distributions)
- ✨ Auto-migration: Users upgrading from v2.x will automatically have their S3 buckets secured with CloudFront-only access on first deploy
v2.1.0
🛡️ Deployment Stability & Resource Management
- ✨ S3 File Cleanup: Automatically delete files from S3 that were removed locally during incremental deploy
- ✨ CloudFront Rollback: Auto-rollback newly created S3 bucket when CloudFront deployment fails
- ✨ Partial Resource Cleanup: ACM/Route53 cleanup on CloudFront deployment failure
- ✨ AWS API Retry: Exponential backoff retry logic for transient AWS errors
- ✨ Extended Timeout: CloudFront deployment timeout increased (20min → 30min)
- ✨ Immediate State Updates: State file updated after each resource deletion (remove command)
New CLI Options:
--no-rollback- Keep S3 bucket even if CloudFront deployment fails--no-cleanup- Skip S3 file cleanup during incremental deploy
Bug Fixes:
- 🔧 Fixed race condition in S3 bucket rollback logic
- 🔧 Fixed duplicate hash comparison during incremental deploy
v2.0.2
- 🔧 Free Plan Compatibility: Fixed error when updating distributions on Free pricing plan
- 🔧
priceClassupdate is now automatically skipped for Free plan distributions - ℹ️ Free plan uses all edge locations (equivalent to PriceClass_All)
v2.0.1
- 🔧 Fixed remaining TTL references in Zod schema and config utils
- 🔧 Updated test cases to remove TTL validation tests
- 📝 Updated README with v2.0.0 changelog
v2.0.0
🆓 CloudFront Free Tier Pricing Plan Compatible
- ✨ Cache Policy Migration: Switched from Legacy cache settings (ForwardedValues) to AWS Managed Cache Policy (CachingOptimized)
- ✨ Free Tier Eligible: Distributions are now compatible with CloudFront's new flat-rate pricing plans (Nov 2025)
- ✨ Pricing Plan Info: After deployment, displays information about CloudFront pricing plans and recommends Free plan
- 🗑️ TTL Options Removed:
defaultTTL,minTTL,maxTTLconfig options removed (now managed by Cache Policy)
CloudFront Pricing Plans (New in Nov 2025):
| Plan | Price | Requests | Transfer | |------|-------|----------|----------| | Free | $0/mo | 1M | 100GB | | Pro | $15/mo | 10M | 50TB | | Business | $200/mo | 125M | 50TB |
Breaking Changes:
- ⚠️ TTL options removed: If you have
defaultTTL,minTTL, ormaxTTLin your config, please remove them - TTL is now managed by AWS Managed Cache Policy (CachingOptimized): Min 1s, Default 1 day, Max 1 year
v1.1.0
🌐 SPA Mode & Client-Side Routing Support
- ✨ SPA Mode (Default Enabled): CloudFront now automatically redirects 403/404 errors to
index.htmlwith 200 status - ✨ Client-Side Routing Support: Works out of the box with React Router, Vue Router, Angular Router, etc.
- ✨ Configurable SPA Mode: Use
spa: falseto disable for static HTML sites that need actual 404 pages - ✨ Custom Error Pages: New
errorPagesconfiguration for fine-grained control - 📝 Init Template Updated: SPA mode option now documented in generated
scf.config.ts
How It Works:
cloudfront: {
enabled: true,
// spa: true, // Default - redirect 403/404 to index.html (SPA)
// spa: false, // Disable SPA mode for static HTML sites
}Breaking Changes:
- None - existing deployments continue to work. SPA mode is additive and enabled by default.
v1.0.0
🎉 Production Ready Release
- 🚀 First stable production release
- 🧪 360+ comprehensive tests (256 unit + 104 integration + E2E)
- 🔄 GitHub Actions CI/CD pipelines (PR + Main workflows)
- 🐶 Enhanced Husky hooks (pre-commit + pre-push with 4-step validation)
- 📝 Comprehensive documentation updates
🧪 Testing Infrastructure
- ✨ 256 unit tests with mocked dependencies
- ✨ 104 integration tests for module interactions
- ✨ E2E tests with real AWS resources (S3, CloudFront, ACM, Route53)
- ✨ Automated test execution in CI/CD
🔄 CI/CD Pipeline
- ✨ PR workflow: Build → Lint → Unit → Integration
- ✨ Main workflow: Full test suite including E2E
- ✨ GitHub Secrets integration for AWS credentials
Breaking Changes:
- None - fully backward compatible with v0.5.0
v0.5.0
🔐 SSL & Custom Domain Automation
- ✨ Zero-configuration HTTPS for custom domains
- ✨ Automatic ACM certificate creation and validation
- ✨ Route53 DNS validation record automation
- ✨ Automatic Route53 hosted zone creation (NEW!)
- ✨ CloudFront A/AAAA alias record creation (NEW!)
- ✨ Certificate reuse detection
- ✨ Domain ownership verification
- 📝 certificateArn is now optional
📦 Enhanced Resource Management
- ✨ Tag-based resource discovery system - Find resources without state files
- ✨ Comprehensive resource tagging - All AWS resources tagged (S3, CloudFront, ACM, Route53)
- ✨ Enhanced recover command - Now discovers ACM certificates and Route53 hosted zones
- ✨ Complete remove command - Delete ACM certificates and Route53 hosted zones
- ✨ Resource listing - View all SCF-managed resources with
recover --all - 🗑️ Remove command now works without state files (tag-based discovery)
🧪 Testing & Quality
- 🧪 143 unit tests (was 130)
- ✅ Comprehensive test coverage for new features
- 🔨 Husky pre-push hooks for build, lint, and test checks
Breaking Changes:
- None - fully backward compatible
Migration Notes:
- Existing deployments will be automatically tagged on next deployment
- No action required - all features work with existing resources
- Recover command can now discover more resources (ACM, Route53)
Links
- Homepage: https://github.com/SCF-org
- Issues: https://github.com/SCF-org/scf/issues
- NPM: https://www.npmjs.com/package/scf-deploy
Author
jeonghodong [email protected]
