For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /ko/docs/desktop/before-you-start.md (or send Accept: text/markdown).

시작하기 전에

Node.js, Git, 편집기, Rust 및 네이티브 빌드 도구를 설치하고, 리포지토리 초대를 수락하고, 키트를 다운로드한 다음 컴퓨터가 첫 번째 데스크톱 실행 준비가 되었는지 확인합니다.

이 가이드에 대해 질문하기

1. 실행하고 싶은 것을 선택하세요

인터넷에 연결된 Windows, macOS 또는 Linux 컴퓨터를 사용합니다. Desktop 앱은 이 같은 컴퓨터에 설치되는 네이티브 창입니다 — 전화기는 관련 없습니다. 아래 단계는 도구를 설치하고 프로젝트를 다운로드합니다.

리포지토리는 GitHub를 통해 받은 파일 폴더입니다. Desktop 구매는 Desktop 키트 리포지토리를 제공하고, All Platforms 번들은 세 개의 앱이 모두 들어 있는 폴더인 모노레포를 제공합니다. 구매한 리포지토리의 초대를 수락하십시오. Desktop 리포지토리에는 Tauri 셸 — 웹 앱을 둘러싼 네이티브 창 — 이 들어 있지만 Web 백엔드는 들어 있지 않으므로 창은 별도로 실행 중인 백엔드 주소에 연결합니다.

이러한 도구를 한 번 준비하십시오. 도구 다운로드 및 첫 번째 기본 컴파일에는 5분보다 훨씬 오래 걸릴 수 있습니다. 이러한 준비 후에 5분 가이드가 시작됩니다. 로컬로 실행하면 앱이 인터넷에 게시되지 않습니다.

2. Node.js 설치

아래의 공식 Node.js 다운로드 페이지를 엽니다. 번호가 22 이상인 LTS 버전과 컴퓨터용 설치 프로그램(Windows의 경우 .msi, macOS의 경우 .pkg)을 선택하세요. 다운로드한 설치 프로그램을 열고 기본값을 유지한 후 설치를 완료합니다. Node.js를 사용하면 컴퓨터에서 앱의 JavaScript를 실행할 수 있습니다. npm가 함께 설치됩니다.

설치 후 터미널을 닫았다가 다시 엽니다. Windows에서 시작을 열고 PowerShell를 입력하여 엽니다. macOS에서는 Command + Space를 누르고 Terminal을 입력한 후 Enter를 누르세요. Linux에서는 애플리케이션 메뉴에서 터미널을 엽니다. 아래 명령을 붙여넣은 후 Enter를 누르세요. v22.x.x 또는 v24.x.x와 같은 결과는 Node를 사용할 수 있음을 확인합니다. 명령을 찾을 수 없거나 인식되지 않는 경우 터미널을 다시 열거나 PATH 옵션이 활성화된 노드를 다시 설치하세요.

공식 Node.js 설치 프로그램

node --version
npm --version

3. Git 및 텍스트 편집기 설치

아래 Git 다운로드 페이지를 열고 운영 체제를 선택한 후 설치 프로그램을 따르세요. Git은 개인 저장소를 다운로드하고 파일 변경 사항을 기록합니다. macOS에서 아래 명령을 실행하면 Apple의 명령줄 도구가 설치될 수 있습니다. 이를 승인하고 완료된 후 명령을 다시 실행하십시오. Linux에서는 Git 페이지에 배포판에 표시된 설치 명령을 사용합니다.

공식 다운로드 페이지에서 Visual Studio Code를 설치하세요. 프로젝트를 열고 구성 파일을 저장하기 위한 텍스트 편집기입니다. 파일을 열고 파일 → 폴더 열기(macOS에서는 파일 → 열기)를 선택한 다음, 나중에 다운로드한 supastack 폴더를 선택하세요. 첫 번째 로컬 데모를 완료하기 위해 코드를 작성할 필요는 없습니다.

새로 열린 터미널에서 아래 명령어를 실행해 보세요. git 버전으로 시작하는 결과는 Git이 준비되었음을 의미합니다. 명령이 누락된 경우 설치 프로그램을 완료하고 터미널을 다시 엽니다.

git --version

4. GitHub 초대를 수락하세요.

구매할 때 제공한 계정을 사용하여 브라우저에서 GitHub에 로그인하세요. GitHub 초대 이메일을 열고 초대 보기를 선택한 후 액세스를 수락하세요. 그런 다음 초대된 저장소를 엽니다. 해당 파일과 녹색 코드 버튼이 표시됩니다. 404는 일반적으로 초대가 수락되지 않았거나 다른 GitHub 계정에 로그인되었음을 의미합니다.

코드 → 로컬 → HTTPS를 선택하고 표시된 주소를 복사하세요. 다음 단계에서 정확한 주소를 사용하세요. 꺾쇠괄호가 포함된 주소의 예는 템플릿입니다. 괄호를 붙여넣는 대신 꺾쇠괄호를 바꾸세요. 조직 이름을 추측하거나 개인 저장소를 공개할 필요가 없습니다.

5. 프로젝트를 컴퓨터에 다운로드

문서와 같은 프로젝트의 폴더를 선택합니다. 파일 탐색기 또는 Finder에서 해당 폴더를 엽니다. Windows에서는 빈 공간을 마우스 오른쪽 버튼으로 클릭하고 터미널에서 열기를 선택한 다음 필요한 경우 PowerShell를 선택합니다. macOS에서 터미널을 열고 cd와 공백을 입력한 후 폴더를 터미널로 드래그하고 Enter 키를 누릅니다. 이제 터미널이 해당 폴더에서 작동 중입니다.

아래 첫 번째 명령에서 YOUR_COPIED_HTTPS_ADDRESS를 방금 복사한 HTTPS 주소로 바꿉니다. 한 번에 한 줄씩 실행합니다. 첫 번째 줄에서는 supastack이라는 새 폴더를 만듭니다. 두 번째 줄이 들어갑니다. Git에서 로그인을 요청하면 브라우저 로그인을 완료하세요. GitHub 계정 비밀번호를 Git 비밀번호로 사용하지 마십시오. 브라우저 로그인이 불가능한 경우, 아래 링크된 GitHub의 HTTPS 인증 가이드를 따르세요.

성공: supastack 폴더에는 package.json, pnpm-workspace.yaml, apps, packages가 있습니다. Desktop 체크아웃은 apps 안에 데스크톱 셸만 표시하고, All Platforms 모노레포는 웹과 모바일 앱도 표시합니다. 이것이 리포지토리 루트입니다. Git이 대상이 이미 존재한다고 말하면 다른 빈 폴더를 사용하거나 기존 클론을 여십시오. 작업을 삭제하지 마십시오. 다음 단계를 위해 이 터미널을 열어 두십시오.

GitHub HTTPS 인증 도움말

git clone YOUR_COPIED_HTTPS_ADDRESS supastack
cd supastack

6. Corepack 및 고정된 패키지 관리자를 확인하세요.

아래의 첫 번째 명령을 실행하세요. Corepack는 package.json에 기록된 pnpm 버전을 선택합니다. pnpm는 프로젝트에서 사용하는 라이브러리를 다운로드합니다. Corepack가 해당 버전을 다운로드할 수 있는 권한을 요청하면 y를 입력하고 Enter를 누르세요. 이 체크아웃 핀은 pnpm 11.19.0입니다. 다른 패키지 관리자를 선택하는 대신 핀을 유지하세요.

corepack이 누락된 경우 npm install --global corepack를 실행하고 터미널을 다시 열고 다시 시도하세요. PowerShell에서 npm.ps1 또는 corepack.ps1 스크립트를 실행할 수 없다고 표시되면 corepack.cmd pnpm install를 포함하여 해당 명령에 npm.cmd 또는 corepack.cmd를 사용하세요. 컴퓨터의 실행 정책을 변경할 필요는 없습니다.

필터링된 첫 실행 명령은 Corepack를 직접 호출합니다. corepack pnpm dev와 같은 Turbo 명령을 사용하는 경우 Turbo에는 PATH에도 pnpm 명령이 필요합니다. 아래 Windows 설정에서는 사용자가 쓸 수 있는 폴더에 해당 명령을 생성합니다. PATH 변경 사항은 현재 터미널에서만 지속됩니다. pnpm가 누락된 경우 새 터미널을 연 후 이 블록을 다시 실행하세요. macOS/Linux에서는 corepack enable를 실행합니다. 권한 오류가 보고되면 필터링된 첫 실행 명령을 대신 사용하세요.

명령어 실행 및 파일 편집 방법 알아보기

corepack --version
corepack pnpm --version

# Windows PowerShell only, for Turbo commands:
$kitShimDir = Join-Path $env:LOCALAPPDATA 'supastack/corepack-shims'
New-Item -ItemType Directory -Path $kitShimDir -Force | Out-Null
corepack enable --install-directory $kitShimDir
$env:PATH = "$kitShimDir;$env:PATH"

7. Rust 및 네이티브 빌드 도구 설치

Windows에서는 아래 Tauri 필수 구성 요소 링크를 사용하여 Microsoft C++ 빌드 도구를 설치합니다. 설치 프로그램에서 C++를 사용한 데스크톱 개발을 선택하고 Windows SDK를 선택한 상태로 유지하고 설치를 완료합니다. Microsoft Edge WebView2 런타임이 설치되어 있는지 확인하세요. Rustup-init.exe를 사용하여 Rustup.rs에서 Rust를 설치하세요. 기본 MSVC 툴체인을 유지합니다. 설치 후 터미널을 다시 엽니다.

macOS에서는 터미널에서 xcode-select --install을 실행하고 명령줄 도구 대화 상자가 설치되지 않은 경우 완료합니다. Rustup.rs에서 macOS 명령을 사용하여 Rust를 설치합니다. Linux에서는 정확한 배포판의 WebKitGTK, 컴파일러, 트레이 및 시스템 라이브러리 패키지에 대한 Tauri 전제 조건 페이지를 따른 다음 Rust를 설치하세요. Linux 패키지 이름은 다양합니다. 다른 배포판의 명령을 실행하지 마십시오.

저장소 루트에서 터미널을 열고 아래 버전 확인을 실행하세요. rustc 및 cargo 모두 버전을 인쇄해야 합니다. cargo는 Rust의 빌드 도구입니다. 둘 중 하나라도 누락된 경우 설치를 완료하고 계속하기 전에 터미널을 다시 엽니다.

rustc --version
cargo --version

8. Desktop 가이드로 계속하기

Node와 Git이 버전을 출력하고, Corepack이 고정된 pnpm을 선택할 수 있고, rustc와 cargo가 버전을 출력하고, 터미널이 package.json이 들어 있는 폴더에 있으면 준비된 것입니다. 아래에서 튜토리얼을 하나 선택하십시오.