scf-deploy - S3 + CloudFront Deployment CLI

Automate static website deployment to AWS S3 and CloudFront with a simple CLI tool.

Features

• Easy Setup: Interactive init command with helpful post-install message
• Simple Deployment: Deploy with a single command npx scf-deploy deploy
• TypeScript Configuration: Type-safe config files with scf.config.ts
• Auto Build Detection: Automatically finds your build directory (dist, build, out, etc.)
• Build Validation: Ensures deployable files exist before creating AWS resources
• Multiple Templates: Pre-configured templates for React, Vue, Next.js
• Incremental Deployment: Only upload changed files (SHA-256 hash comparison)
• CloudFront Integration: Automatic cache invalidation after deployment
• Multi-Environment Support: Manage dev, staging, and prod environments
• AWS Credentials Integration: Supports AWS profiles, environment variables, and IAM roles
• State Management: Track deployed resources locally with automatic .gitignore handling
• State Recovery: Recover lost state files from AWS resource tags
• Progress Tracking: Real-time upload progress with visual feedback
• SSR Detection: Prevents accidental deployment of SSR builds (.next, .nuxt)

Installation

Global Installation

npm install -g scf-deploy

Direct Execution with npx (Recommended)

npx scf-deploy deploy

Quick Start

1. Initialize Configuration

Run the init command to create scf.config.ts:

npx scf-deploy init

This will guide you through an interactive setup or you can use defaults:

npx scf-deploy init --yes

Or 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: {
    enabled: true,
    // 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. Build Your Site

# For React, Vue, etc.
npm run build

# For plain HTML
# Just make sure your files are in the buildDir

3. Deploy

npx scf-deploy deploy

That's it! Your site is now live on S3 and CloudFront.

Configuration

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: {
    enabled: true,
    // priceClass: 'PriceClass_100',  // Optional: PriceClass_100, PriceClass_200, PriceClass_All
  },
};

export default config;

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, 11ty
• output - Some SSGs

Requirements:

• Directory must contain index.html as 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 files

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: {
    enabled: true,
  },

  // Environment overrides
  environments: {
    dev: {
      s3: { bucketName: 'my-site-dev' },
      cloudfront: { enabled: false },  // Skip CloudFront in dev
    },
    staging: {
      s3: { bucketName: 'my-site-staging' },
    },
    prod: {
      cloudfront: { priceClass: 'PriceClass_All' },  // Use all edge locations in prod
    },
  },
};

export default config;

Custom Domain Configuration

import type { SCFConfig } from 'scf-deploy';

const config: SCFConfig = {
  app: 'my-app',
  region: 'us-east-1',

  s3: {
    bucketName: 'my-site',
  },

  cloudfront: {
    enabled: true,
    customDomain: {
      domainName: 'example.com',
      certificateArn: 'arn:aws:acm:us-east-1:123456789012:certificate/abc-def',
    },
  },
};

export default config;

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 --force

Options:

• -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

# Skip CloudFront (S3 only)
scf-deploy deploy --no-cloudfront

# Force full deployment (ignore cached state)
scf-deploy deploy --force

Options:

• -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
• --no-cloudfront - Skip CloudFront deployment
• --force - Force full deployment (ignore state)
• --skip-cache - Skip CloudFront cache invalidation

remove

Remove deployed AWS resources.

# Remove 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

Options:

• -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

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 --json

Options:

• -e, --env <environment> - Environment name (default: "default")
• -d, --detailed - Show detailed information
• --json - Output as JSON

recover

Recover lost deployment state from AWS resources.

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

# Overwrite existing state file
scf-deploy recover --force

How it works:

1. Searches for S3 buckets with scf:managed=true tag
2. Finds associated CloudFront distributions
3. Filters by app name and environment
4. Reconstructs the state file from AWS resources

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

Note: All AWS resources created by scf-deploy are automatically tagged for recovery:

• scf:managed=true - Indicates resource is managed by scf-deploy
• scf:app=<app-name> - Application name from config
• scf:environment=<env> - Environment name

AWS Credentials

scf-deploy looks for AWS credentials in the following order:

1. Command-line option: --profile flag
2. Environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
3. AWS CLI profiles: ~/.aws/credentials
4. IAM Role: When running on EC2, ECS, etc.

Using AWS Profile

scf-deploy deploy --profile my-company-profile

Using Environment Variables

export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
scf-deploy deploy

Features 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 .gitignore if it doesn't exist
• One-time: Only modifies once, won't duplicate entries

This happens automatically during:

• scf-deploy init - When initializing configuration
• scf-deploy deploy - After first successful deployment

State Recovery

If you accidentally delete .deploy/state.json, you can recover it:

scf-deploy recover --env prod

How it works:

• All AWS resources are tagged with scf:managed, scf:app, scf:environment
• recover command searches for these tagged resources
• State file is reconstructed from AWS metadata
• You can continue deploying without recreating resources

What can be recovered:

• S3 bucket information
• CloudFront distribution ID and domain
• Resource creation timestamps
• Environment configuration

Note: File hashes are not recoverable, so the next deployment will re-upload all files.

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:

1. Creates or updates CloudFront distribution
2. Invalidates cache for changed files
3. Waits for distribution to be fully deployed
4. Shows real-time progress

CloudFront Cache Warming

Reduce cold start latency by pre-warming CloudFront edge locations after deployment:

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)
  },
}

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:

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,
      },
    },
  },
}

Multi-Environment Support

Manage multiple environments with ease:

scf-deploy deploy --env dev
scf-deploy deploy --env staging
scf-deploy deploy --env prod

Each 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 prod

Configuration:

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: {
    enabled: true,
  },
};

export default config;

Vue Application

# Build your Vue app
npm run build

# Deploy
scf-deploy deploy

Configuration:

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: {
    enabled: true,
  },
};

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: {
    enabled: true,
  },
};

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 deploy

AWS Credentials Error

# Verify AWS credentials
aws sts get-caller-identity

# Use specific profile
scf-deploy deploy --profile my-profile

Config file not found

# Check if scf.config.ts exists
ls -la scf.config.ts

# Specify custom path
scf-deploy deploy --config ./config/scf.config.ts

State file conflicts

# Check state files
ls -la .deploy/

# Force full redeployment
scf-deploy deploy --force

Build 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 prod

Requirements

• Node.js: >= 18.0.0
• AWS Account: With appropriate permissions
• AWS Credentials: Configured via CLI, environment, or IAM role

Required AWS Permissions

{
  "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": "*"
    }
  ]
}

Note: Tagging permissions are required for the state recovery feature.

Best Practices

1. Build before deploying: Always run your build command before deployment

   npm run build && npx scf-deploy deploy

2. State file management:

   • .deploy/ is automatically added to .gitignore
   • Never commit state files to Git
   • Use scf-deploy recover if state is lost

3. Use environment-specific configs: Separate dev/staging/prod

   scf-deploy deploy --env dev    # For development
   scf-deploy deploy --env prod   # For production

4. Test with --dry-run first: Preview changes before deploying

   scf-deploy deploy --dry-run

5. Use 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

6. Enable CloudFront in production: Better performance and HTTPS

   • Disable CloudFront in dev to save costs
   • Use PriceClass_100 for cost optimization
   • Upgrade to PriceClass_All for global coverage

7. Set up custom domain with ACM certificate: Professional appearance

   • Request ACM certificate in us-east-1 for CloudFront
   • Verify domain ownership
   • Add domain to CloudFront config

8. Static export for Next.js: Use output: 'export'

   // next.config.js
   module.exports = {
     output: 'export',
   };

9. Monitor AWS costs:

   • Check S3 storage and transfer costs
   • Monitor CloudFront data transfer
   • Use CloudWatch for usage metrics

10. Keep your CLI updated:

    npm update -g scf-deploy
    # Or with npx (always uses latest)
    npx scf-deploy@latest deploy

Testing

SCF uses Jest as the testing framework with comprehensive unit tests for core functionality.

Running Tests

# Run all tests
npm test

# Run only unit tests
npm run test:unit

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

Test Structure

src/__tests__/
├── unit/              # Unit tests for core modules
│   ├── config/        # Config parsing, validation, merging
│   ├── deployer/      # File scanning, hashing
│   └── state/         # State management
├── integration/       # Integration tests (future)
├── e2e/              # End-to-end tests (future)
└── fixtures/          # Test data and config files

Test Coverage

Current test coverage for core modules:

Total Unit Tests: 130 tests

Writing Tests

When contributing, please ensure:

1. Add tests for new features: All new functionality should include tests
2. Maintain coverage: Keep coverage above 90% for core modules
3. Use fixtures: Add test data to src/__tests__/fixtures/
4. 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 tests
• test:unit - Run only unit tests
• test:watch - Run tests in watch mode
• test:coverage - Generate coverage report (saved to coverage/)

Coverage reports are generated in:

• HTML: coverage/index.html (open in browser)
• LCOV: coverage/lcov-report/ (for CI/CD tools)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE file for details

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 fire13764@gmail.com