템플릿 ZIP에서 실행 환경을 빼면 받는 사람은 압축을 푸는 일 외에 설치 단계도 맡게 된다. 파일이 작아졌다는 안내와 함께, 어떤 프로그램이 있어야 하고 어느 폴더에서 무엇을 실행할지 알려줘야 한다.
처음에는 다른 PC에서도 바로 쓸 수 있도록 Windows와 Mac용 실행 환경을 함께 넣어 달라는 요청이었다. 이후 도구가 이미 설치돼 있으니 실행 환경은 빼고 README에 준비 조건을 적는 것으로 바뀌었다. 이 변경은 압축 크기뿐 아니라 설치할 사람의 작업도 바꿨다. 안내문·패키징 코드·검증 기록을 기준으로 그 차이를 살펴본다.
받는 PC에 무엇이 있는지부터 정했다
처음의 통합 전달본은 Windows와 Mac의 CPU 종류에 맞는 Node.js 실행 환경과 의존성, 실행기, 미리보기를 포함했다. 압축을 푼 뒤 별도 Node.js 설치 없이 시작하게 하려는 구성이다. 사용자가 설치된 도구를 쓰겠다고 정정한 뒤에는 실행 파일과 설치 패키지, node_modules, 예제 빌드와 검수 화면을 제외하는 템플릿 전용 구성으로 바뀌었다.
현재 README의 조건은 Node.js 22 이상과 npm이다. 프로젝트 의존성을 설치하려면 인터넷에 연결되거나 필요한 패키지가 npm 캐시에 있어야 한다. Node.js만 설치돼 있다고 프로젝트의 패키지까지 준비된 것은 아니다. 실행 환경을 동봉하지 않는 구성에는 이 설치 단계를 함께 안내해야 한다.
어느 쪽을 선택할지는 수신자의 환경에 달려 있다. 실행 도구를 설치하기 어려운 PC에 템플릿 전용 ZIP을 보내면 안내만으로 해결되지 않을 수 있다. 반대로 사용할 도구가 이미 있는 사람에게 여러 운영체제의 실행 파일을 모두 보낼 필요도 줄어든다. 이 판단은 압축률을 조절하기 전에 해야 한다.
다시 설치할 것과 반드시 옮길 것을 구분한다
확인한 소형 패키징 코드는 실행 환경과 설치된 의존성을 제외하면서 화면 코드·폰트·공통 아이콘·자료 양식·설계 계약·라이선스를 남긴다. 템플릿을 다른 현장에 적용하는 데 필요한 구성을 먼저 정하고, 미리보기 산출물은 전달 대상에서 뺀 것이다.
새 현장을 생성한 뒤에는 그 현장의 숨김 .engine 폴더가 중요하다. README는 새 현장을 다시 옮길 때 이 폴더를 포함하라고 안내한다. 새 현장의 빌드 명령도 그 안의 실행 코드를 참조한다. 화면 자료만 복사하고 숨김 폴더를 빠뜨리면, 원래 작업 PC에서는 되던 명령이 다음 PC에서 실행되지 않을 수 있다.
새 PC에서 의존성을 다시 설치하는 것은 안내된 준비 절차다. 반면 템플릿 엔진을 빠뜨리면 작업 파일이 누락된 것이다. README에는 설치할 항목과 함께 옮겨야 할 항목을 나눠 적어야 한다.
설치 명령에는 현재 폴더도 포함한다
실제 README는 템플릿 엔진 폴더에서 의존성을 설치하고, 새 현장을 만든 뒤 그 현장 폴더에서도 의존성을 설치하도록 안내한다. npm ci가 두 번 보이는 이유는 실행 위치가 달라졌기 때문이다. 명령만 남기고 작업 폴더를 생략하면 같은 프로젝트에서 중복 실행하라는 뜻으로 오해할 수 있다.
아래는 안내문의 새 현장 이름만 example-site로 바꾼 명령 예시다. 이번 집필에서 실행한 명령은 아니다. 생성 뒤에는 해당 현장의 실제 사진·문구·자료를 채워야 한다. README는 빈 양식에 필수 자료가 없어 빌드가 차단된다고 설명한다.
자료를 채운 새 현장에서 npm run preview:build와 npm run preview를 실행한다. 이 미리보기는 실제 신청 접수와 이메일 전송을 차단한다. 화면을 볼 수 있다는 것과 실제 문의가 전달되는 운영 환경이 연결됐다는 것은 다른 결과다.
코드와 구현 살펴보기
Installation sequence from the template guide; folder name is illustrative
cd "현장교체형"
npm ci
node scripts/cli.mjs init --output "../example-site"
cd "../example-site"
npm ci검증 기록도 전달본의 버전과 함께 읽었다
과거 소형 패키지의 기록에는 압축을 별도 경로에 풀고 README 명령으로 준비한 뒤, 새 현장을 생성·빌드하고 로컬 경로 응답을 확인한 결과가 있다. 원본 운영 자료가 들어 있지 않아 원본 보존 비교는 생략됐다는 설명도 남아 있다. 검사를 통과한 항목과 검사할 자료가 없었던 항목을 합쳐 전체 통과로 쓰지 않는다.
별 효과 수정 뒤 전달 ZIP도 갱신됐다. 집필 당시에는 최초 패키지의 해시를 쓰지 않고 최신 패키지 기록의 바이트 수·해시와 보관 ZIP을 대조했다. ZIP 안의 README도 그때의 원본 안내문과 같았다. 파일과 기록의 일치를 확인한 것이며 설치나 원제품 시험을 다시 실행한 것은 아니다.
Windows의 과거 실행 확인과 Mac의 파일·실행 권한·스크립트 확인도 범위가 다르다. 원래 안내문은 Mac 실기기 실행을 미확인으로 남겼다. Windows와 Mac에서 같은 Node.js 명령을 사용하도록 구성했다는 설명을 모든 PC에서 실행을 마쳤다는 말로 넓히지 않는다.
전달받는 사람이 파일 크기와 함께 읽어야 할 것은 남은 준비 조건이다. 실행 도구의 포함 여부, 의존성 설치 방법, 새 현장 엔진과 자료의 위치, 확인한 환경과 단계를 README에 남길 수 있다. 이번 글에서는 그 조건을 대조했으며, 원래 패키지를 다시 만들거나 설치·삭제·배포하지 않았다.