create-m2m-bo-template-react

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

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

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

• npm 패키지: https://www.npmjs.com/package/create-m2m-bo-template-react
• 버전 관리 / 배포: 완전 자동 (아래 배포 참고). 수동 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 를 직접 실행해서 결과물 눈으로 확인

Vercel 웹앱 배포

앱은 BrowserRouter를 사용하며, 주소는 /members 같은 일반 경로를 유지합니다. vercel.json의 rewrite가 서브페이지 요청에 /index.html을 제공하므로 직접 접속하거나 새로고침할 때도 React Router가 해당 화면을 표시합니다.

| 배포 대상 | Vercel Root Directory | 적용 설정 | | --- | --- | --- | | 이 저장소 전체 | 저장소 루트 | 루트 vercel.json이 template의 의존성을 설치하고 빌드하여 template/dist를 배포 | | 이 저장소의 앱 폴더 | template | template/vercel.json, Vite 기본 빌드(npm run build, 출력 dist) | | CLI로 생성한 프로젝트 | 생성한 프로젝트 루트 | 함께 복사된 vercel.json, Vite 기본 빌드 |

설정 파일을 반영한 뒤 Vercel에서 재배포해야 적용됩니다. 참고: Vercel의 Vite SPA rewrite 안내.

template/ 작업 규칙

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

| 규칙 | 이유 | | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | 점(.)으로 시작하는 파일은 _ 접두사로 저장 (_gitignore, _env.example 등) | npm 은 배포 시 .gitignore·.npmrc 등 일부 점파일을 자동으로 제외함. index.js 가 복사 시 다시 . 로 바꿔줌 | | template/node_modules, 빌드 산출물 커밋 금지 | 루트 .gitignore 에 이미 포함 | | 템플릿 전용 lint/prettier 설정은 template/ 안에 자체적으로 둔다 | 루트 도구가 template/ 를 무시하도록 설정돼 있음 | | template/ 내용을 바꾸면 smoke-test.mjs 의 검증도 같이 보강한다 | 깨진 스캐폴드가 배포되는 것을 막기 위함 |

새 점파일을 추가할 때는 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)

파이프라인 잡

| Job | 실행 시점 | 내용 | | --------- | --------------------------------- | -------------------------------------------------------------------------------------------- | | test | Merge Request 이벤트, main push | node smoke-test.mjs — 스캐폴드가 정상 동작하는지 검증 | | release | main push 만 | npx semantic-release — 버전 결정 → npm publish → GitLab Release/태그 생성 → 버전 반영 커밋 |

배포 트리거

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 별 동작

| type | 버전 변화 | 예시 | | ------------------------------------------------------------------- | ------------------------- | ------------------------------------------ | | fix | patch (1.0.0 → 1.0.1) | fix: 스캐폴드 시 빈 폴더 검사 누락 수정 | | feat | minor (1.0.0 → 1.1.0) | feat: vite + react + ts 기본 템플릿 추가 | | feat / fix + BREAKING CHANGE | major (1.0.0 → 2.0.0) | 아래 참고 | | chore, docs, ci, refactor, test, style, perf, build | 릴리스 없음 | docs: README 배포 절차 보강 |

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 react 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 에 등록 (프로젝트 관리자 작업).

| Key | 값 | 플래그 | | -------------- | ---------------------------------------------------------------------- | ----------------- | | NPM_TOKEN | npm Automation 액세스 토큰 (npmjs.com → Access Tokens) | Masked | | GITLAB_TOKEN | GitLab 액세스 토큰, scope: api, write_repository, role: Maintainer | Masked, Protected |

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

트러블슈팅

| 증상 | 원인 / 조치 | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | 파이프라인이 계속 pending | 프로젝트에 러너 미할당. Settings → CI/CD → Runners 에서 러너 활성화. 태그 불일치면 .gitlab-ci.yml 의 tags: 조정 | | node: command not found / npm ci 실패 | 러너 호스트에 Node 22+ / npm / git 미설치 | | semantic-release shallow clone 경고 후 실패 | CI/CD Variables 에 GIT_DEPTH = 0 추가 | | @semantic-release/git push 거부 | protected main 에 토큰 사용자 push 권한 부여, 또는 .releaserc.json 에서 해당 플러그인 제거 | | npm publish 403 | NPM_TOKEN 이 Automation 타입인지, 패키지명 소유권/2FA 정책 확인 | | main 에 push 했는데 버전이 안 오름 | 커밋에 feat/fix 가 없음 (chore 등만 있으면 정상적으로 릴리스 생략됨) |

License

MIT