내려받기와 설치

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이 이미 익숙하다면 git clone

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) 본인 GitHub 저장소 연결 확인

이 다음부터 본인이 만드는 모든 commit 은 본인 GitHub 저장소로 올라갑니다. 연결이 제대로 됐는지 한 번만 확인하고 넘어갑니다.

git remote -v

A 경로로 받았다면 다음 두 줄이 보입니다.

origin  https://github.com/<your-id>/my-saas.git (fetch)
origin  https://github.com/<your-id>/my-saas.git (push)

본인 저장소 주소가 origin 으로 등록돼 있다면 끝입니다. 이후 git push 한 줄로 본인 저장소에 변경분이 올라갑니다.

B 경로로 받았는데 origin 이 보이지 않거나 base 주소가 그대로 남아 있다면, 본인 GitHub에 빈 저장소를 먼저 만들고 다음 두 줄로 연결합니다.

git remote add origin https://github.com/<your-id>/my-saas.git
git push -u origin main

-u 플래그는 다음 push 부터 git push 만 입력해도 같은 곳으로 가도록 설정해 둡니다. 처음 한 번만 필요한 플래그입니다.

ddakit base 의 원격은 10-staying-up-to-date.md 에서 base 라는 다른 이름으로 다시 등록합니다. 본인 저장소인 origin 과 ddakit 갱신 채널인 base 가 한 저장소에 함께 등록되는 구조입니다.

3) 의존성 설치

pnpm install

pnpm 이 처음이라면 한 줄로 설치됩니다.

npm install -g pnpm

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

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

4) 빠른 점검

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

이전 빌드에서 남은 파일이 새 설치와 충돌하는 경우가 가끔 있습니다.

5) 빌드가 동작하는지 한 번 확인

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

pnpm run typecheck

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

6) 선택 사항: 내 프로젝트로 다듬기

여기까지 오면 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으로 갑니다.