내려받기와 설치

01-prerequisites.md에서 여섯 항목을 끝냈다면 이 단계는 보통 5~10분 정도 걸립니다.

1) base를 내 프로젝트로 가져오기

base를 받는 방법은 두 가지가 있습니다. git이 처음이면 GitHub Template 쪽이 친절합니다.

A. GitHub Template — 권장

base의 GitHub 페이지(github.com/ddakit/saas-base)를 엽니다.
우측 상단의 초록색 Use this template 버튼을 누르고 Create a new repository를 고릅니다.
본인 GitHub 계정 아래 새 저장소 이름을 정합니다. 예: my-saas.
Create repository 를 누릅니다.

내 계정 아래에 base의 새 복제본이 만들어집니다. 이제 그 복제본을 컴퓨터로 받아 옵니다. 터미널을 열고 다음 명령을 실행합니다.

cd ~/Desktop                                # 또는 원하는 작업 폴더
git clone https://github.com/<your-id>/my-saas.git
cd my-saas

<your-id> 자리에는 본인 GitHub 사용자명을 넣어 주세요.

B. 그냥 git clone — git이 이미 익숙하다면

git clone https://github.com/ddakit/saas-base.git my-saas
cd my-saas
git remote remove origin                    # base의 원격 연결 끊기
# 본인 GitHub에 빈 저장소를 만든 다음, 그 주소로 원격을 다시 연결합니다:
# git remote add origin https://github.com/<your-id>/my-saas.git

base 원격은 끊지 말고 다른 이름으로 다시 잡아 두면 10-staying-up-to-date.md 단계에서 그대로 씁니다. git remote rename origin base 를 먼저 친 다음 본인 저장소를 origin 으로 새로 잡는 흐름도 한 방법입니다.

2) 의존성 설치

pnpm install

pnpm 이 처음이라면 한 줄로 깔립니다.

npm install -g pnpm

도중에 빨간 줄이 뜨면 화면에 출력된 안내를 먼저 따라가 보세요. 그래도 풀리지 않으면 09-troubleshooting.md의 “pnpm install 이 권한 에러로 실패합니다” 항목으로 갑니다.

이 단계가 처음이면 한 번에 안 풀리는 경우가 적지 않습니다. 가장 흔한 원인은 1단계의 nvm 활성화가 새 터미널에 안 따라간 경우입니다. 새 터미널 창을 열고 node --version 부터 다시 확인하면 깔끔하게 풀리는 경우가 많습니다.

3) 빠른 점검

ls node_modules | head -5

react, vite, @supabase, @tanstack, react-router-dom 같은 폴더 이름이 출력되면 설치가 잘 끝난 것입니다. 아무것도 안 보이거나 node_modules 폴더 자체가 없다고 나오면 2단계가 실패한 상태입니다.

이전 시도가 실패한 흔적이 남아 있는 경우라면 node_modules/ 와 pnpm-lock.yaml 을 한 번 깨끗이 지우고 다시 시작합니다.

rm -rf node_modules pnpm-lock.yaml
pnpm install

이전 빌드의 잔여 파일이 새 설치와 충돌하는 경우가 가끔 있습니다.

4) 빌드가 도는지 한 번 확인

본격적인 첫 실행은 다음 단계에서 합니다. 다만 환경이 정말 잡혔는지 한 번만 확인해 두면 다음 단계 진입이 편합니다.

pnpm run typecheck

tsc --noEmit 가 한 바퀴 돌고 끝납니다. 에러가 없으면 줄 하나만 짧게 떨어지고, 에러가 있으면 빨간 출력이 따라옵니다. 이 시점에서 에러가 보인다면 의존성 설치가 깨끗하지 않은 상태이니, 위 3단계의 rm -rf 자리를 한 번 더 돌리고 다시 시도합니다.

5) 선택 사항 — 내 프로젝트로 다듬기

여기까지 오면 base가 내 컴퓨터에 자리를 잡은 상태입니다. 지금 바로 내 SaaS로 다듬고 싶다면 package.json의 이름과 설명, index.html 의 title, README의 첫 단락을 본인 정보로 바꿉니다. base의 LICENSE 와 COMMERCIAL-LICENSE.md 는 그대로 둡니다. 템플릿 사용 권한은 goldtagworks와의 별도 상업 라이선스 계약으로 정해진다고 적혀 있는 파일입니다.

지금 당장 다듬을 필요는 없습니다. 첫 실행이 정상으로 도는지 먼저 확인한 다음에 손대도 늦지 않습니다. 브랜딩과 디자인 톤은 05-customize-design.md 에서 한 번에 갈아 끼웁니다.

pnpm install 과 pnpm run typecheck 가 깔끔하게 끝났다면 03-first-run.md으로 갑니다.