runlot.json
프로젝트 디렉터리에 두는 설정 파일입니다. 이름, 진입점, 자산 디렉터리 및 연결한 서비스를 기록합니다.
web/apps/cli/src/config.ts 및 internal/bundle/bundle.go입니다. 문서를 빌드할 때 해당 소스에서 내용을 생성합니다.{
"name": "my-app",
"org": "me",
"main": "src/index.ts",
"assets": "public",
"database": true
}필드
| 필드 | 자료형 | 필수 | 설명 |
|---|---|---|---|
name | string | 예 | 프로젝트 이름입니다. 배포 URL의 첫 번째 라벨로 사용됩니다. |
org | string | 아니오 | 조직 slug입니다. --org 옵션을 지정하면 이 설정보다 우선합니다. |
main | string | 아니오 | 워커의 진입점입니다. 지정하지 않으면 정적 자산만 배포합니다. |
assets | string | 아니오 | 정적 자산 디렉터리입니다. |
notFound | `"404" | "spa"` | 아니오 |
compatibilityDate | string | 아니오 | workerd 호환성 날짜입니다. 형식은 YYYY-MM-DD입니다. |
database | boolean | 아니오 | 데이터베이스를 쓴다는 선언입니다. runlot deploy가 읽고, 없으면 만듭니다. |
storage | boolean | 아니오 | 파일 저장소를 쓴다는 선언입니다. runlot deploy가 읽고, 없으면 만듭니다. |
email | boolean | 아니오 | 이메일 발신·수신 선언 (docs/email.md) |
auth | boolean | 아니오 | 애플리케이션 사용자 인증을 쓴다는 선언입니다. runlot deploy가 읽고, 없으면 켭니다. 데이터베이스도 함께 만듭니다. |
framework | "next" | 아니오 | 프레임워크 어댑터입니다. 현재 지원하는 값은 next뿐입니다. |
triggers | { crons: string[] } | 아니오 | 예약 실행입니다. crons 에 5 필드 cron 표현식을 UTC 로 적습니다. 자세한 내용은 예약 실행에 있습니다. |
name은 필수입니다. main과 assets 가운데 하나 이상을 지정해야 합니다. 둘 다 없으면 제공할 워커나 정적 자산이 없습니다. framework를 지정한 프로젝트는 예외이며, 빌드 과정에서 진입점과 자산을 생성합니다.
서비스를 선언하는 필드
database, storage, auth는 선언입니다. runlot deploy가 이 값을 읽어 아직 없는 서비스를 만듭니다. wrangler 설정의 바인딩 선언과 같은 자리이며, 켜는 명령이나 대시보드 버튼은 따로 없습니다. 만드는 일은 멱등이므로 같은 선언으로 여러 번 배포해도 서비스는 하나입니다.
선언을 지워도 서비스는 남습니다. 지우는 것은 runlot pg delete, runlot storage delete, runlot auth delete이며 확인을 거칩니다. auth는 데이터베이스가 있어야 하므로 "auth": true만 적어도 데이터베이스를 함께 만듭니다.
각 서비스는 프로젝트마다 하나씩만 연결할 수 있으므로 서비스 이름 대신 true로 선언합니다. 워커에서는 각각 env.db, env.storage, env.auth로 접근합니다.
번들 매니페스트
runlot deploy는 이 설정 파일을 그대로 업로드하지 않습니다. CLI는 빌드 결과를 참조하는 별도의 runlot.json 매니페스트를 번들에 생성합니다. 사용자가 직접 작성할 필요는 없지만, 아래 유효성 검사 규칙이 적용됩니다.
| 필드 | 설명 |
|---|---|
main | 번들에 포함되는 워커 진입 모듈입니다. 없으면 정적 자산만 제공하는 진입점이 자동으로 추가됩니다. |
assets | 번들에 포함되는 자산 디렉터리입니다. / 와 확장자 없는 경로는 index.html 로 답하고, Content-Type 은 확장자로 정합니다. |
notFound | 404(기본) 또는 spa. spa 면 확장자 없는 경로를 /index.html 로 답합니다. |
compatibilityDate | 형식은 YYYY-MM-DD입니다. 지정하지 않으면 2024-09-23를 사용합니다. |
compatibilityFlags | 허용 목록 방식의 호환성 플래그입니다. 현재 사용할 수 있는 값은 nodejs_compat뿐입니다. |
modules | 추가 모듈 목록입니다. wasm 자료형만 지원합니다. |
framework | 프레임워크 어댑터입니다. 현재 지원하는 값은 next뿐입니다. |
triggers | 예약 실행입니다. crons 는 5 필드 cron 표현식(UTC)이고, 배포 시점에 해석해 틀린 것은 거절합니다. main 이 있어야 합니다. |
compatibilityFlags는 허용 목록 방식입니다. 어떤 매니페스트도 사용자 코드에 프로세스 전체 제어 권한을 부여하는 플래그를 활성화할 수 없어야 하기 때문입니다. 번들이 Node 내장 모듈을 import하면 nodejs_compat가 필요하므로 CLI가 자동으로 설정합니다.
WASM은 modules 필드를 통해서만 포함할 수 있습니다. workerd는 번들 내부에서 new WebAssembly.Module(bytes)를 호출해 컴파일하는 방식을 허용하지 않습니다. Prisma 쿼리 컴파일러가 이 제약의 영향을 받습니다.
번들 제한
| 항목 | 제한 |
|---|---|
| 압축된 업로드 크기 | 64 << 20 |
| 압축 해제 후 전체 크기 | 512 << 20 |
| 파일 하나의 크기 | 64 << 20 |
| 파일 수 | 20_000 |
번들에는 일반 파일만 포함할 수 있습니다. 심볼릭 링크, 프로젝트 루트 밖을 가리키는 경로, 중복된 항목은 모두 거부됩니다.