create-m2m-bo-template-vue

create-m2m-bo-template-vue

M2M 백오피스 vue 템플릿을 생성하는 스캐폴딩 CLI입니다.

사용자가 아래 명령을 실행하면 이 저장소의 template/ 폴더 내용이 대상 디렉토리로 복사됩니다.

npm create m2m-bo-template-vue@latest my-app
# 또는
npx create-m2m-bo-template-vue my-app

• npm 패키지: https://www.npmjs.com/package/create-m2m-bo-template-vue
• 버전 관리 / 배포: 완전 자동 (아래 배포 참고). 수동 npm publish·태그 생성 금지.

저장소 구조

.
├─ index.js            # CLI 본체. template/ 를 대상 폴더로 복사하고 _파일 → .파일 로 rename
├─ template/           # ★ 실제로 배포되는 프로젝트 원본. 여기에 소스/설정을 채운다
│  ├─ package.json     # 생성될 프로젝트의 package.json (현재는 placeholder)
│  └─ _gitignore       # 생성 시 .gitignore 로 변환됨
├─ smoke-test.mjs      # CI 테스트: 스캐폴드 실행 → 결과물 검증
├─ .gitlab-ci.yml      # 파이프라인 정의 (test / release)
├─ .releaserc.json     # semantic-release 설정
├─ package.json        # CLI 패키지 메타. version 은 semantic-release 가 관리
└─ .nvmrc             # Node 버전 (22)

index.js 동작

1. 대상 디렉토리가 비어 있는지 확인 (비어있지 않으면 종료)
2. template/ 전체를 대상 디렉토리로 복사
3. 대상 디렉토리 최상위에서 _ 로 시작하는 파일을 . 로 시작하도록 rename (_gitignore → .gitignore, _npmrc → .npmrc 등)

로컬 개발

Node.js 22 이상 필요 (.nvmrc 참고).

npm install

npm test            # smoke-test.mjs 실행. ./__smoke 에 스캐폴드 후 결과 검증, 끝나면 삭제
npm run lint        # eslint (템플릿 폴더는 검사 대상 아님)
npm run format      # prettier --check
npm start -- my-app # CLI 를 직접 실행해서 결과물 눈으로 확인

template/ 작업 규칙

template/ 안의 내용이 그대로 최종 사용자에게 전달됩니다. 배포하려는 실제 vue 프로젝트(소스, 설정 파일, 디렉토리 구조)를 이 폴더에 구성하세요.

새 점파일을 추가할 때는 index.js 의 rename 로직이 최상위 파일만 처리한다는 점에 유의. 하위 디렉토리의 점파일이 필요하면 index.js 를 확장해야 합니다.

배포 (CI/CD)

인프라

• GitLab CI (.gitlab-ci.yml) 로 동작
• 실행 주체: 사내 Windows self-hosted runner (shell executor, pwsh)
  • 러너 호스트에 node(22+), npm, git 이 PATH 에 있어야 함
  • 러너가 태그 제한 + "Run untagged jobs" 꺼짐 상태면 .gitlab-ci.yml 의 default: 에 tags: [<러너태그>] 추가 필요
• 릴리스 자동화: semantic-release (.releaserc.json)

파이프라인 잡

배포 트리거

main 브랜치에 커밋이 올라가야만 배포 파이프라인(release)이 돕니다. feature 브랜치 push 나 MR 단계에서는 test 만 돌고 배포되지 않습니다.

release 잡에서 semantic-release 가 하는 일:

1. 마지막 릴리스 태그 이후의 커밋 메시지를 분석해 다음 버전을 계산
2. 릴리스할 변경이 없으면(예: chore: 커밋만 있음) 아무것도 하지 않고 종료
3. package.json 의 version 을 새 버전으로 갱신
4. npm publish 로 npmjs.com 에 배포
5. GitLab Release 와 vX.Y.Z 태그 생성, 릴리스 노트 자동 작성
6. 갱신된 package.json 을 main 에 chore(release): X.Y.Z [skip ci] 커밋으로 되돌림

커밋 메시지 규칙 (필수)

버전과 릴리스 여부는 커밋 메시지로 결정됩니다. Conventional Commits 형식을 반드시 지키세요.

<type>(<scope>): <제목>

<본문 - 선택>

<footer - 선택>

type 별 동작

perf 는 설정에 따라 patch 가 될 수 있으나 현재 설정에서는 릴리스되지 않습니다. 성능 개선이 사용자에게 영향 있으면 fix 로 커밋하세요.

BREAKING CHANGE (major)

두 가지 방법 중 하나:

feat!: 템플릿 최소 Node 버전을 20 → 22 로 상향

또는 footer 에 명시:

feat: 라우팅 구조 전면 개편

BREAKING CHANGE: pages 디렉토리 규칙이 바뀌어 기존 생성물과 호환되지 않음

scope (선택, 권장)

변경 범위를 괄호로 표기하면 릴리스 노트 가독성이 좋아집니다.

feat(template): 공통 레이아웃 컴포넌트 추가
fix(cli): 대상 경로에 공백이 있을 때 처리
ci: 러너 태그 설정 추가

규칙 위반 시

• type 없이 커밋(템플릿 수정함)하면 semantic-release 가 무시 → 배포 안 됨
• 여러 변경을 한 커밋에 섞지 말 것. 가장 큰 영향의 type 으로 집계됩니다.

작업 → 배포 흐름

1. 브랜치 생성            git switch -c feat/base-template
2. template/ 작업 + smoke-test 보강
3. 커밋                   git commit -m "feat(template): vite vue ts 기본 구조 추가"
4. push & MR 생성         → 파이프라인에서 test 잡 통과 확인
5. MR 을 main 으로 머지    (Squash 시 커밋 메시지도 Conventional Commits 형식 유지)
6. main 파이프라인        release 잡이 semantic-release 실행 → npm 자동 배포
7. 결과 확인              GitLab → Deployments/Releases, npmjs.com 버전

주의

• package.json 의 version 을 직접 수정하지 마세요. semantic-release 가 관리합니다.
• 수동으로 git tag 를 만들거나 npm publish 하지 마세요.
• MR Squash 머지를 쓴다면, 머지 커밋 제목이 최종 커밋 메시지가 되므로 형식을 지켜야 합니다.

필수 CI/CD 변수

Settings → CI/CD → Variables 에 등록 (프로젝트 관리자 작업).

• @semantic-release/npm 이 NPM_TOKEN 을 .npmrc 에 자동으로 씁니다.
• GITLAB_TOKEN 은 Release 생성(api)과 버전 커밋 push(write_repository)에 사용됩니다.
• main 이 protected 브랜치면 해당 토큰 사용자가 push 가능해야 합니다 (Settings → Repository → Protected branches → Allowed to push).

트러블슈팅

License

MIT