Configuration

SCF uses scf.config.ts for configuration.

Basic Structure

typescript

import { defineConfig } from 'scf-deploy';

export default defineConfig({
  app: 'my-site',           // Required
  region: 'ap-northeast-2', // Required
  s3: { ... },              // S3 settings
  cloudfront: { ... },      // CloudFront settings
  environments: { ... },    // Environment overrides
});

Required Options

Option	Type	Description
`app`	`string`	Application name (lowercase, hyphens)
`region`	`string`	AWS region

S3 Options

Option	Type	Default	Description
`bucketName`	`string`	-	Required. S3 bucket name (globally unique)
`buildDir`	`string`	auto	Build directory (auto-detects: dist, build, out)
`indexDocument`	`string`	`index.html`	Index document (used by CloudFront Function)
`errorDocument`	`string`	-	Error document
`exclude`	`string[]`	`[]`	Files to exclude
`concurrency`	`number`	`10`	Max concurrent uploads
`gzip`	`boolean`	`true`	Enable Gzip compression

Note (v3.0.0): S3 buckets are only accessible through CloudFront OAC. Direct S3 URL access is not available.

typescript

s3: {
  bucketName: 'my-site-bucket-abc123',
  buildDir: './dist',
  exclude: ['*.map', '.DS_Store'],
}

CloudFront Options

v3.0.0 Change: CloudFront is now always enabled for security. The enabled option has been removed. S3 buckets are only accessible through CloudFront OAC (Origin Access Control).

Option	Type	Default	Description
`priceClass`	`string`	`PriceClass_100`	Edge location coverage
`ipv6`	`boolean`	`true`	Enable IPv6
`spa`	`boolean`	`true`	SPA mode (redirects 403/404 to index.html)
`customDomain`	`object`	-	Custom domain settings
`cacheWarming`	`object`	-	Cache warming settings
`errorPages`	`array`	-	Custom error pages

Cache Policy (v2.0.0+)

SCF uses AWS Managed Cache Policy (CachingOptimized) for optimal performance. TTL settings are managed automatically by AWS.

Automatic TTL Values:

Setting	Value
MinTTL	1 second
DefaultTTL	86400 seconds (1 day)
MaxTTL	31536000 seconds (1 year)

💡 Tip: Manual TTL configuration is no longer needed. AWS automatically manages cache behavior for optimal performance.

Price Classes

Value	Coverage
`PriceClass_100`	North America, Europe (cheapest)
`PriceClass_200`	+ Asia, Middle East, Africa
`PriceClass_All`	All locations (best performance)

typescript

cloudfront: {
  priceClass: 'PriceClass_100',
}

Custom Domain

typescript

cloudfront: {
  customDomain: {
    domainName: 'www.example.com',
    // certificateArn is optional - auto-created with Route53
    aliases: ['example.com'],
  },
}

SPA (Single Page Application) mode is enabled by default. When enabled, CloudFront automatically redirects 403/404 errors to index.html, allowing client-side routing (React Router, Vue Router, etc.) to work properly.

typescript

cloudfront: {
  spa: true, // Default: true (no configuration needed)
}

To disable SPA mode:

typescript

cloudfront: {
  spa: false, // Disable SPA mode
}

Custom Error Pages

When spa: true (default), SPA works without any errorPages configuration. For more granular error page control, you can configure errorPages directly:

typescript

cloudfront: {
  spa: false, // Disable SPA mode when using custom error pages
  errorPages: [
    {
      errorCode: 404,
      responseCode: 200,
      responsePath: '/index.html',
      cacheTTL: 300, // Cache error response for 5 minutes
    },
    {
      errorCode: 403,
      responseCode: 200,
      responsePath: '/index.html',
    },
  ],
}

Cache Warming

typescript

cloudfront: {
  cacheWarming: {
    enabled: true,
    paths: ['/', '/about'],
    concurrency: 3,
    delay: 500, // Delay between requests (ms)
  },
}

Multi-Environment

typescript

export default defineConfig({
  app: 'my-site',
  region: 'ap-northeast-2',

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

  cloudfront: {
    // CloudFront is always enabled (OAC security)
  },

  environments: {
    dev: {
      s3: { bucketName: 'my-site-dev' },
    },
    prod: {
      s3: { bucketName: 'my-site-prod' },
      cloudfront: { priceClass: 'PriceClass_All' },
    },
  },
});

Deploy with environment:

bash

npx scf-deploy deploy --env prod

Complete Example

typescript

import { defineConfig } from 'scf-deploy';

export default defineConfig({
  app: 'my-site',
  region: 'ap-northeast-2',

  s3: {
    bucketName: 'my-site-bucket-abc123',
    exclude: ['*.map'],
  },

  cloudfront: {
    priceClass: 'PriceClass_100',
    errorPages: [
      { errorCode: 404, responseCode: 200, responsePath: '/index.html' },
    ],
  },

  environments: {
    prod: {
      s3: { bucketName: 'my-site-prod' },
      cloudfront: {
        priceClass: 'PriceClass_All',
        customDomain: {
          domainName: 'www.example.com',
        },
      },
    },
  },
});

Migration Guide

v2.x → v3.0.0 Migration

If you're upgrading from v2.x, remove the following options from your scf.config.ts:

typescript

// Before (v2.x)
cloudfront: {
  enabled: true,  // ❌ Remove - no longer needed
  priceClass: 'PriceClass_100',
}

// After (v3.0.0)
cloudfront: {
  // CloudFront is always enabled for security
  priceClass: 'PriceClass_100',
}

Key Changes:

cloudfront.enabled option removed - CloudFront is always enabled
s3.websiteHosting option removed - S3 website hosting disabled
Direct S3 bucket access not available - use CloudFront URL only

v1.x → v2.0.0 Migration

If you're upgrading from v1.x, remove the following TTL options from your scf.config.ts:

typescript

// Before (v1.x) - These options are no longer supported
cloudfront: {
  enabled: true,
  defaultTTL: 3600,     // ❌ Remove
  maxTTL: 86400,        // ❌ Remove
  minTTL: 0,            // ❌ Remove
}

// After (v2.0.0)
cloudfront: {
  enabled: true,
  // TTL is now managed automatically by AWS Managed Cache Policy
}

⚠️ Note: If you keep TTL settings in your config, they will be ignored in v2.0.0+. The AWS Managed Cache Policy (CachingOptimized) provides optimal caching behavior automatically.