Orbit에서 지원하는 프레임워크 및 런타임

Orbit builds any project that installs with npm, yarn or pnpm and produces a folder of files or a Node.js server, and it detects the framework and package manager for you so most projects deploy…

Orbit가 npm, yarn 또는 pnpm으로 설치되고 파일 폴더 또는 Node.js 서버를 생성하는 모든 프로젝트를 빌드하며, 프레임워크와 패키지 매니저를 자동으로 감지하므로 대부분의 프로젝트는 빌드 구성 없이 배포됩니다. 이 가이드에서는 감지되는 항목, 각 일반 프레임워크에 필요한 설정, 서버 모드를 켜야 하는 경우, Node.js 버전을 선택하는 방법을 다룹니다.

Orbit가 자동으로 감지하는 항목

빌드가 실행되면 Orbit은 찾은 항목을 기록하고 다시 표시합니다:

프레임워크, 배포 상세 페이지와 프로젝트 개요의 배포 카드에 배지로 표시됩니다.
패키지 매니저, 잠금 파일에서 선택: package-lock.json는 npm, yarn.lock는 yarn, pnpm-lock.yaml는 pnpm을 제공합니다.

설정의 빌드 설정은 모두 선택 사항입니다. 필드를 비워두면 자리 표시자가 대신 사용될 내용을 표시합니다: 설치 명령어는 npm ci (auto-detected)를 표시하고, 빌드 명령어는 npm run build (auto-detected)를 표시하며, 출력 디렉터리는 dist (auto-detected)을 표시합니다.

Orbit 프로젝트 설정의 빌드 설정

정확히 하나의 잠금 파일을 커밋하세요. package-lock.json와 yarn.lock가 모두 저장소에 있으면, Orbit이 선택하는 패키지 매니저가 로컬에서 사용하는 것과 다를 수 있으며, 보이는 이유 없이 머신과 다르게 동작하는 설치가 발생합니다. 사용하지 않는 것을 삭제하세요.

프레임워크별 설정

각 프레임워크에 필요한 값들입니다. Orbit이 프레임워크에 대한 스타터 템플릿을 제공하는 경우, 템플릿은 정확히 이 설정을 사용합니다.

프레임워크	빌드 명령어	출력 디렉터리	서버 모드
Next.js, 정적 내보내기	`npm run build`	`out`	꺼짐
Next.js, SSR 또는 ISR	`npm run build`	`.next`	켜짐
Astro, 정적	`astro build`	`dist`	꺼짐
Astro, 서버 또는 하이브리드	`astro build`	`dist`	켜짐
Vite (React, Vue, Svelte)	`npm run build`	`dist`	꺼짐
SvelteKit	`npm run build`	`build`	어댑터에 따라 결정
Nuxt 3	`npm run build`	`.output`	켜짐
Remix	`npm run build`	`build`	켜짐
Express 또는 일반 Node API	`npm run build`	`dist`	켜짐
Create React App	`npm run build`	`build`	꺼짐
일반 HTML 또는 정적 생성기	비워두거나 생성기의 명령어	`.` 또는 쓰는 폴더	꺼짐

Vite는 vite.config.ts에서 build.outDir을 설정하지 않은 한 항상 dist에 씁니다. Astro의 출력 폴더는 모든 모드에서 dist이며, 모드 간에 변하는 것은 파일이 어디에 저장되는지가 아니라 서버 모드가 필요한지 여부입니다.

서버 모드

서버 모드는 설정의 런타임 아래에 있는 토글입니다. 켜져 있으면 Orbit은 각 배포 후 정적 파일 폴더를 제공하는 대신 npm start을 실행하는 빌드 머신을 활성 상태로 유지합니다.

SSR이 있는 Next.js, Remix, Nuxt, Express API 및 정적 내보내기가 아닌 다른 모든 항목에 대해 켜세요. 진정한 정적 빌드의 경우 꺼두세요.

현재 라이브 배포가 아니라 다음 배포부터 적용됩니다.

서버 모드 누락의 전형적인 증상은 홈페이지는 완벽하게 로드되지만 모든 동적 경로가 404를 반환하는 사이트입니다. 빌드는 성공했고, 파일은 게시되었으며, 경로에 응답하기 위해 실행 중인 서버가 단순히 없습니다. 이것을 보고 있다면 서버 모드를 켜고 다른 것을 변경하기 전에 재배포하세요.

Node.js 버전

설정의 빌드 설정 아래에서 Node.js 버전을 설정하세요. 주 버전 번호만 입력하세요: 18, 20 또는 22. 플랫폼 기본값을 사용하려면 비워두세요.

버전은 빌드 및 서버 모드가 켜져 있을 때 런타임에 모두 적용됩니다.

기본값에 의존하지 말고 버전을 명시적으로 고정하세요. 기본값보다 최신 Node가 필요한 종속성은 명백하지 않게 설치에 실패하고, 고정하면 "어제는 작동했는데"라는 빌드 실패 전체 카테고리가 제거됩니다.

모노레포

루트 디렉터리를 앱이 포함된 하위 디렉터리(예: apps/web)로 설정하세요. Orbit은 설치 및 빌드 명령어를 실행하기 전에 해당 디렉터리로 변경합니다.

또한 원하지만 예상하지 못할 수 있는 작업도 수행합니다: 해당 경로 외부의 파일만 변경하는 푸시는 자동으로 건너뜁니다. 따라서 4개의 Orbit 프로젝트가 있는 모노레포는 커밋이 실제로 터치한 앱만 다시 빌드합니다.

각 환경은 설정의 스테이징: 빌드 오버라이드 아래에서 루트 디렉터리를 별도로 오버라이드할 수 있으며, 이는 스테이징이 다른 워크스페이스를 빌드할 때 유용합니다.

사용자 정의 빌드 설정

설정의 빌드 설정 아래에서 항목을 오버라이드하세요:

필드	예시	설명
설치 명령어	`npm ci`	또는 `yarn install --frozen-lockfile`, `pnpm install --frozen-lockfile`
빌드 명령어	`npm run build:prod`	정확히 쓰인 대로 실행
출력 디렉터리	`dist/client`	빌드 후 게시되는 폴더
루트 디렉터리	`apps/frontend`	모노레포 하위 디렉터리
Node.js 버전	`20`	주 버전만

비워두면 자동 감지됩니다. 빌드 설정 카드의 저장을 클릭하여 적용하세요.

스테이징은 스테이징: 빌드 오버라이드 섹션에서 이 중 하나를 독립적으로 오버라이드할 수 있습니다. 거기서 비워둔 필드는 프로젝트 수준 값을 상속하므로 스테이징에 대해 빌드 명령어만 변경하고 다른 모든 것을 그대로 둘 수 있습니다.

빌드 캐시

Orbit은 Liftoff 및 Apex 플랜에서 빌드 간에 node_modules을 캐시합니다. 캐시가 사용되면 배포는 캐시 히트 배지를 표시하고 설치 단계는 훨씬 짧습니다. 캐시 없는 빌드는 콜드 빌드를 표시합니다.

전체 재설치를 강제하려면 설정을 열고, 빌드 캐시 지우기를 클릭하고, 확인하세요. 각 환경의 다음 배포는 처음부터 전체 설치를 실행합니다. 이는 취소할 수 없으며, 이후의 빌드는 느립니다.

빌드 머신 리소스

빌드 머신 크기는 계획에 따라 다르며, 이는 큰 빌드에 중요합니다:

플랜	vCPU	RAM	디스크	시간 제한
Launch	1	1 GB	4 GB	30분
Liftoff	2	2 GB	8 GB	30분
Apex	4	4 GB	16 GB	30분

메모리 부족이나 디스크 가득 찬 빌드는 배포 페이지에서 해당 실패 카테고리로 이름이 지어져 실패합니다. NODE_OPTIONS=--max-old-space-size를 높이면 머신의 실제 RAM까지만 도움이 됩니다.

템플릿에서 시작

저장소를 갖기 전에 작동하는 배포를 원하면 스타터 템플릿을 사용하세요. 새 프로젝트에서 Git 저장소 가져오기에서 템플릿에서 시작으로 전환하고 하나를 선택하세요: shadcn/ui가 포함된 Next.js, Astro 마케팅 사이트, Remix Indie Stack, SvelteKit 스타터, 최소한의 Nuxt 3 앱 또는 Express REST API. Orbit이 템플릿을 복사하고, 올바른 빌드 설정을 적용하고, 배포합니다.