Cloudflare Workers Types 날짜별 엔트리포인트 제거 전에 타입 설정 바꾸기
날짜별 타입을 설정 기반 생성 타입으로 바꿔야 한다
Cloudflare Workers Types 마이그레이션을 미뤄둔 프로젝트라면 먼저 시점부터 바로잡아야 해요. 날짜별 엔트리포인트는 앞으로 없어질 예정이 아니라, 2026년 7월 3일 공개된 @cloudflare/workers-types v5에서 이미 제거됐습니다. 앱 Worker는 날짜가 붙은 패키지 경로를 루트 import로 슬쩍 바꾸는 대신, Wrangler 설정을 읽어 타입을 생성하고 TypeScript와 CI에 연결하는 쪽이 현재 권장 경로예요.
이 글은 2026년 7월 31일 기준 Cloudflare 변경 로그와 Workers TypeScript 공식 문서를 대조해 정리했습니다. 직접 프로젝트에 패키지를 설치하거나 tsc를 실행한 결과는 아니며, 특정 프레임워크나 모노레포에서 생길 수 있는 충돌까지 재현한 글도 아닙니다. 공식 구문을 실제 운영 순서로 재배열한 분석임. 이 선은 분명히 긋고 시작합니다.
제거 경계는 미래 날짜가 아니라 v5다
Cloudflare의 2026년 7월 3일 변경 로그에 따르면 v5가 제공하는 엔트리포인트는 두 가지예요.
@cloudflare/workers-types: 최신 compatibility date와 안정 상태의 compatibility flags를 반영한 타입@cloudflare/workers-types/experimental: 실험 플래그 뒤에 있는 API를 반영한 타입
반면 아래처럼 날짜가 붙은 경로는 v5에서 제거됐습니다.
@cloudflare/workers-types/YYYY-MM-DD
여기서 없어진 건 Worker 런타임 API 전체가 아니라 v5 패키지의 날짜별 타입 엔트리포인트예요. @cloudflare/workers-types 패키지 자체도 폐지된 게 아닙니다. Cloudflare는 계속 발행할 계획이며 Workers용 라이브러리나 공유 패키지에는 여전히 이 패키지를 권장한다고 설명해요.
또 하나 조심할 부분. 공식 자료는 v5라는 제거 경계는 밝혔지만 v4 계열의 날짜별 경로를 언제까지 별도 지원하는지는 제시하지 않았습니다. 그래서 “2026년 7월 3일부터 기존 설치가 전부 즉시 깨졌다”거나 특정 미래 날짜까지 강제 전환해야 한다고 말할 수는 없음. 잠금 파일과 설치 버전에 따라 각 프로젝트 상태가 다를 수 있어요.
먼저 날짜별 참조와 Wrangler 설정을 같이 찾는다
프로젝트 안에서 @cloudflare/workers-types/YYYY-MM-DD 형태를 찾습니다. 소스의 type import만 보지 말고 tsconfig.json의 compilerOptions.types, 삼중 슬래시 참조, 별도 .d.ts 파일도 확인할 만해요. 이 위치들은 일반적인 TypeScript 참조 지점을 정리한 적용 판단이며, Cloudflare가 특정 검색 명령까지 제시한 것은 아닙니다.
그다음 Wrangler 설정에서 아래 항목을 함께 확인해요.
compatibility_datecompatibility_flags- bindings
rules- environment 구성
왜 날짜만 보면 안 되나 싶었는데, 이유가 꽤 명확합니다. Workers TypeScript 문서는 올바른 타입이 날짜와 플래그뿐 아니라 bindings와 rules에도 좌우된다고 설명해요. 같은 날짜라도 플래그가 다르면 필요한 런타임 타입이 달라질 수 있음.
그래서 날짜별 경로를 @cloudflare/workers-types 루트로만 치환하는 건 같은 결과가 아닙니다. 루트는 최신 안정 타입을 제공하고, 생성 타입은 해당 앱의 실제 Wrangler 설정을 기준으로 삼아요. 배포되는 애플리케이션 Worker라면 후자가 딱 맞는 선택입니다.
중요한 주의점도 하나. 타입을 맞추려고 compatibility_date를 오늘 날짜로 올릴 필요는 없어요. 날짜 변경은 런타임 동작을 바꿀 수 있는 별도 작업입니다. 우선 현재 배포 날짜와 플래그에 타입을 맞추고, 날짜 업데이트는 테스트를 거쳐 따로 판단하는 편이 안전해요. 마음 급하다고 두 작업을 한 번에 묶으면 변경 원인 찾기가 난감해짐.
Wrangler 버전에 맞춰 타입을 생성한다
Wrangler v4를 쓰는 앱 Worker라면 기본 명령은 간단합니다.
npx wrangler types
기본 결과는 worker-configuration.d.ts이며 런타임 타입과 bindings 기반 Env 타입을 함께 포함해요. Env가 필요하지 않다면 --include-env=false를 쓸 수 있습니다.
다만 Wrangler 3.x까지 같은 명령과 파일 경로라고 생각하면 안 됩니다.
| Wrangler 범위 | 공식 문서상 처리 |
|---|---|
| v4 | wrangler types로 compatibility date와 flags에 맞는 런타임 타입 생성 |
>3.66.0, <4.0.0 |
wrangler types --experimental-include-runtime 사용, 런타임 타입은 기본적으로 .wrangler/types/runtime.d.ts에 별도 출력 |
<=3.66.0 |
현재 문서는 런타임 타입에 @cloudflare/workers-types 패키지를 이용한다고 안내 |
즉 새 마이그레이션은 v4 경로를 기본으로 잡되, 프로젝트의 Wrangler 버전을 먼저 확인해야 해요. v4용 기본 파일명만 복사해서 3.x 프로젝트의 tsconfig에 넣으면 경로부터 어긋날 수 있습니다. 은근 이런 데서 시간 순삭.
앱과 공유 패키지는 선택이 다르다
| 사용 맥락 | 권장 선택 | 판단 기준 |
|---|---|---|
| 배포되는 애플리케이션 Worker | Wrangler v4의 wrangler types |
실제 날짜, 플래그, bindings, rules를 반영 |
| Workers용 라이브러리·공유 패키지 | @cloudflare/workers-types |
최신 안정 런타임 타입을 대상으로 공유 |
| 실험 API를 패키지로 참조 | @cloudflare/workers-types/experimental |
실험 플래그 뒤 API용 |
| 특정 compatibility date에 고정된 앱 | wrangler types |
날짜별 패키지 경로 대신 설정의 날짜와 플래그를 입력으로 사용 |
/experimental도 특정 앱의 전체 배포 설정과 정확히 일치하는 생성 타입의 대체라고 단정하면 안 됩니다. 앱과 라이브러리를 같은 방식으로 몰아가지 않는 게 핵심이에요.
생성 파일을 tsconfig에 연결한다
Wrangler v4의 기본 경로를 사용했다면 tsconfig.json에서 생성 선언 파일을 포함합니다.
{
"compilerOptions": {
"types": ["./worker-configuration.d.ts"]
}
}
사용자 지정 출력 경로로 생성했다면 types 값도 같은 경로로 맞춰야 해요. 그 뒤 기존 날짜별 패키지 참조를 제거합니다.
nodejs_compat 플래그를 사용하는 프로젝트는 한 단계가 더 있어요. 공식 문서는 @types/node를 설치하고 compilerOptions.types에 "node"도 넣도록 안내합니다. 이건 Workers 런타임 타입 생성과 별개의 보완 설정이에요.
{
"compilerOptions": {
"types": ["./worker-configuration.d.ts", "node"]
}
}
설정 파일 하나 만들었으니 끝… 이라고 하기엔 아직 이릅니다. 생성물이 현재 설정과 맞는지, 그 타입으로 실제 소스가 컴파일되는지까지 확인해야 마이그레이션이 닫힙니다.
CI는 생성물 최신성과 소스 컴파일을 따로 막는다
생성 파일을 저장소에 커밋하는 팀이라면 CI에 두 단계를 순서대로 둡니다.
- run: npx wrangler types --check
- run: npx tsc --noEmit
첫 번째 wrangler types --check는 Wrangler 설정으로 다시 계산한 타입과 커밋된 생성 파일이 같은지 확인해요. 다르면 파일을 새로 쓰지 않고 non-zero 상태로 종료합니다. Cloudflare의 --check 변경 로그가 보장하는 범위는 여기까지예요.
두 번째 tsc --noEmit은 생성 타입을 사용해 애플리케이션 소스를 실제로 컴파일 검사합니다. 이 명령은 공식 문서가 안내한 “타입 생성 뒤 TypeScript 의존 작업을 실행한다”는 원칙을 명확한 두 단계 게이트로 만든 적용 예시예요. 프로젝트에 별도 type-check 스크립트가 있다면 그 명령을 사용해야 합니다.
정리하면 이렇습니다.
wrangler types --check: 생성 선언 파일이 Wrangler 설정과 같은가tsc --noEmit또는 프로젝트의 type-check: 소스 코드가 그 선언과 함께 컴파일되는가
둘은 잡는 회귀가 달라요. --check 하나만 통과했다고 애플리케이션 타입 오류까지 검사됐다고 보면 곤란합니다.
생성 파일을 커밋하지 않는 팀이라면 방식도 달라져요. CI에서 먼저 wrangler types로 파일을 만들고, 이어서 build/type-check/test를 실행하면 됩니다. 공식 문서는 생성 파일 커밋을 선택 사항으로 두므로 어느 한 전략만 정답은 아님.
여러 environment라면 로컬과 CI의 범위를 맞춘다
2026년 1월 13일 변경 이후 wrangler types는 기본적으로 Wrangler 설정에 정의된 모든 environment의 bindings를 모아 생성 Env 타입에 넣습니다. 특정 환경만 필요하면 아래처럼 제한해요.
npx wrangler types --env production
마이그레이션 diff에 예상보다 많은 binding이 나타났다고 해서 날짜별 엔트리포인트 제거의 부작용으로 바로 단정하면 안 됩니다. 다중 environment 변경 로그에 나온 현재 기본 동작 때문일 수 있어요.
중요한 건 로컬과 CI가 같은 범위를 선택하는 것. 로컬은 --env production인데 CI는 전체 환경을 합치면 생성물 비교가 계속 흔들릴 수 있습니다. 설정은 맞는데 검사 방식이 다른 총체적난국 상황, 피해야 함.
이 순서대로 바꾸면 된다
- 설치된
@cloudflare/workers-types와 Wrangler 버전을 확인합니다. - 프로젝트 범위에서 날짜별 엔트리포인트 참조 위치를 찾습니다.
- Wrangler의 날짜, 플래그, bindings,
rules, environment를 검토합니다. - v4에서는
npx wrangler types를 실행하고, 3.x는 앞의 버전 분기를 적용합니다. - 생성 경로를
compilerOptions.types에 넣고 날짜별 참조를 제거합니다. nodejs_compat를 쓴다면@types/node와"node"포함 여부를 확인합니다.- 프로젝트의 type-check/build/test를 실행합니다.
- 생성 파일을 커밋한다면
wrangler types --check뒤 실제 type-check를 CI에 둡니다. - 다중 environment의 생성 범위를 로컬과 CI에서 동일하게 맞춥니다.
이 순서는 공식 마이그레이션 내용을 운영 흐름으로 재구성한 것이에요. 실제 명령은 사용하는 패키지 매니저와 프로젝트 스크립트에 맞게 조정해야 합니다.
결국 이번 변경은 날짜 문자열 하나를 다른 import로 바꾸는 작업이 아니었어요. 앱 Worker는 배포 설정에서 타입을 생성하고, 생성물 최신성과 소스 컴파일을 각각 막아야 마무리됩니다. 공유 라이브러리라면 패키지 타입이 여전히 맞을 수 있고요. 역할 구분만 해두면 생각보다 깔끔함.
타입 마이그레이션 뒤에는 Cloudflare Workers createTestHarness() 통합 테스트로 프로덕션 빌드 동작까지 확인하세요.
FAQ
v5로 올리지 않으면 날짜별 엔트리포인트를 계속 써도 되나요?
공식 자료는 날짜별 엔트리포인트가 v5에서 제거됐다고 밝히지만, v4 계열의 별도 지원 종료일은 제시하지 않습니다. 따라서 기존 설치가 언제까지 동작한다고 단정할 수는 없어요. 설치 버전과 잠금 파일을 확인하고, v5 전환 전 또는 전환으로 깨진 참조를 설정 기반 생성 타입으로 옮기는 편이 자연스럽습니다.
@cloudflare/workers-types 루트 import로만 바꾸면 충분한가요?
공유 라이브러리라면 적합할 수 있지만, 배포되는 앱 Worker에는 같은 결과가 아닙니다. 루트 엔트리포인트는 최신 안정 타입이고, wrangler types 생성물은 프로젝트의 compatibility date, flags, bindings, rules를 반영해요.
compatibility_date를 올리지 않고도 현재 날짜에 맞는 타입을 만들 수 있나요?
네. Wrangler 설정의 현재 compatibility_date와 플래그를 그대로 입력으로 wrangler types를 실행하면 됩니다. 타입 마이그레이션 때문에 날짜를 최신으로 올리는 작업은 런타임 동작 변경과 섞일 수 있으므로 별도로 검토해야 해요.
wrangler types --check가 TypeScript 컴파일도 검사하나요?
아니요. 이 명령은 생성 파일이 현재 Wrangler 설정과 일치하는지 확인합니다. 소스 타입 회귀는 이후 tsc --noEmit이나 프로젝트의 type-check 스크립트로 따로 검사해야 합니다.
여러 environment의 bindings 타입은 어떻게 생성되나요?
현재 기본 동작은 모든 environment의 bindings를 모아 Env 타입에 포함하는 것입니다. 특정 환경만 원하면 wrangler types --env production처럼 제한하고, 로컬과 CI에서 같은 옵션을 사용하세요.
