설정 가이드

SCF는 scf.config.ts 파일로 설정합니다.

기본 구조

typescript

import { defineConfig } from 'scf-deploy';

export default defineConfig({
  app: 'my-site',           // 필수
  region: 'ap-northeast-2', // 필수
  s3: { ... },              // S3 설정
  cloudfront: { ... },      // CloudFront 설정
  environments: { ... },    // 환경별 설정
});

필수 옵션

옵션	타입	설명
`app`	`string`	앱 이름 (소문자, 하이픈만 사용)
`region`	`string`	AWS 리전

S3 옵션

옵션	타입	기본값	설명
`bucketName`	`string`	-	필수. S3 버킷 이름 (전 세계에서 유일해야 함)
`buildDir`	`string`	자동 감지	빌드 폴더 경로 (dist, build, out 자동 감지)
`indexDocument`	`string`	`index.html`	기본 문서 (CloudFront Function에서 사용)
`errorDocument`	`string`	-	에러 페이지
`exclude`	`string[]`	`[]`	업로드 제외 파일 패턴
`concurrency`	`number`	`10`	동시 업로드 수
`gzip`	`boolean`	`true`	Gzip 압축 활성화

참고 (v3.0.0): S3 버킷은 CloudFront OAC를 통해서만 접근 가능합니다. 직접 S3 URL로 접근할 수 없습니다.

typescript

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

CloudFront 옵션

v3.0.0 변경사항: CloudFront는 보안을 위해 항상 활성화됩니다. enabled 옵션이 제거되었습니다. S3 버킷은 CloudFront OAC(Origin Access Control)를 통해서만 접근 가능합니다.

옵션	타입	기본값	설명
`priceClass`	`string`	`PriceClass_100`	엣지 서버 범위
`ipv6`	`boolean`	`true`	IPv6 활성화
`spa`	`boolean`	`true`	SPA 모드 (403/404 에러를 index.html로 리다이렉트)
`customDomain`	`object`	-	커스텀 도메인 설정
`cacheWarming`	`object`	-	캐시 미리 로드 설정
`errorPages`	`array`	-	커스텀 에러 페이지 설정

캐시 정책 (v2.0.0+)

SCF는 최적의 성능을 위해 AWS Managed Cache Policy (CachingOptimized)를 사용합니다. TTL 설정은 AWS에서 자동으로 관리됩니다.

자동 TTL 값:

설정	값
MinTTL	1초
DefaultTTL	86400초 (1일)
MaxTTL	31536000초 (1년)

💡 팁: 수동 TTL 설정이 더 이상 필요하지 않습니다. AWS가 최적의 성능을 위해 캐시 동작을 자동으로 관리합니다.

가격 등급

값	적용 지역
`PriceClass_100`	북미, 유럽 (가장 저렴)
`PriceClass_200`	+ 아시아, 중동, 아프리카
`PriceClass_All`	전 세계 (최상의 성능)

typescript

cloudfront: {
  priceClass: 'PriceClass_100',
}

커스텀 도메인

typescript

cloudfront: {
  customDomain: {
    domainName: 'www.example.com',
    // certificateArn 생략 시 Route53으로 자동 발급
    aliases: ['example.com'],
  },
}

SPA 모드

SPA(Single Page Application) 모드는 기본적으로 활성화되어 있습니다. 이 모드가 활성화되면 CloudFront가 403/404 에러를 자동으로 index.html로 리다이렉트하여 React Router, Vue Router 등의 클라이언트 사이드 라우팅이 정상 동작합니다.

typescript

cloudfront: {
  spa: true, // 기본값: true (별도 설정 불필요)
}

SPA 모드를 비활성화하려면:

typescript

cloudfront: {
  spa: false, // SPA 모드 비활성화
}

커스텀 에러 페이지 설정

spa: true(기본값)일 때는 별도의 errorPages 설정 없이도 SPA가 정상 동작합니다. 더 세밀한 에러 페이지 제어가 필요한 경우 errorPages를 직접 설정할 수 있습니다:

typescript

cloudfront: {
  spa: false, // 커스텀 에러 페이지 사용 시 SPA 모드 비활성화
  errorPages: [
    {
      errorCode: 404,
      responseCode: 200,
      responsePath: '/index.html',
      cacheTTL: 300, // 에러 응답 캐시 시간 (5분)
    },
    {
      errorCode: 403,
      responseCode: 200,
      responsePath: '/index.html',
    },
  ],
}

캐시 미리 로드

typescript

cloudfront: {
  cacheWarming: {
    enabled: true,
    paths: ['/', '/about'],
    concurrency: 3,
    delay: 500, // 요청 간 딜레이 (밀리초)
  },
}

환경별 설정

typescript

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

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

  cloudfront: {
    // CloudFront는 항상 활성화 (OAC 보안)
  },

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

환경 지정해서 배포하기:

bash

npx scf-deploy deploy --env prod

전체 설정 예제

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

마이그레이션 가이드

v2.x → v3.0.0 마이그레이션

v2.x에서 업그레이드하는 경우 scf.config.ts에서 다음 옵션을 제거하세요:

typescript

// 이전 (v2.x)
cloudfront: {
  enabled: true,  // ❌ 제거 - 더 이상 필요 없음
  priceClass: 'PriceClass_100',
}

// 이후 (v3.0.0)
cloudfront: {
  // CloudFront는 보안을 위해 항상 활성화됩니다
  priceClass: 'PriceClass_100',
}

주요 변경사항:

cloudfront.enabled 옵션 제거 - CloudFront가 항상 활성화됨
s3.websiteHosting 옵션 제거 - S3 웹사이트 호스팅 비활성화
S3 버킷 직접 접근 불가 - CloudFront URL만 사용 가능

v1.x → v2.0.0 마이그레이션

v1.x에서 업그레이드하는 경우 scf.config.ts에서 다음 TTL 옵션을 제거하세요:

typescript

// 이전 (v1.x) - 더 이상 지원되지 않는 옵션
cloudfront: {
  enabled: true,
  defaultTTL: 3600,     // ❌ 제거
  maxTTL: 86400,        // ❌ 제거
  minTTL: 0,            // ❌ 제거
}

// 이후 (v2.0.0)
cloudfront: {
  enabled: true,
  // TTL은 이제 AWS Managed Cache Policy에서 자동으로 관리됩니다
}

⚠️ 참고: v2.0.0 이상에서 TTL 설정을 유지하면 무시됩니다. AWS Managed Cache Policy (CachingOptimized)가 최적의 캐싱 동작을 자동으로 제공합니다.