빌드와 패키징

manifest.config.ts가 어떻게 manifest.json을 생성하는지, Vite와 @crxjs/vite-plugin이 dev에서 어떻게 변경 감지를 도는지, pnpm run build와 pnpm run package가 각각 무엇을 떨구는지를 봅니다. architecture에서 잡은 FSD 트리가 여기서 manifest와 만나 chrome이 로드 가능한 산출물이 됩니다.

파이프라인 한 장

graph LR
  src[src/ — FSD 슬라이스]
  manifest[manifest.config.ts]
  vite[vite + @crxjs/vite-plugin]
  dist[dist/ — 로드 가능한 확장]
  zip[packages/extension.zip]

  src --> vite
  manifest --> vite
  vite --> dist
  dist --> zip

src/의 React/TS 코드와 manifest.config.ts가 함께 vite로 들어가고, pnpm run build가 dist/를 떨굽니다. pnpm run package는 그 dist를 zip으로 묶을 뿐입니다.

manifest.config.ts

저장소 루트의 manifest.config.ts는 TypeScript 객체를 export 합니다. crxjs가 제공하는 defineManifest로 감싸면 빌드 시 manifest.json으로 직렬화됩니다.

import { defineManifest } from '@crxjs/vite-plugin'

export default defineManifest({
  manifest_version: 3,
  name: '__MSG_extName__',
  version: '0.1.0',
  permissions: ['storage', 'activeTab'],
  host_permissions: [],
  action: { default_popup: 'src/app/popup/index.html' },
  options_page: 'src/app/options/index.html',
  background: { service_worker: 'src/app/background/index.ts' },
  content_scripts: [
    { matches: ['https://*.example.com/*'], js: ['src/app/content/index.ts'] },
  ],
})

손볼 자리는 permissions, host_permissions, content_scripts.matches, action.default_popup, options_page, side_panel.default_path 정도입니다. 권한을 손댈 때는 design-manifest 스킬을 통해 ADR 한 장과 같이 다듬는 편이 안전합니다. 직접 손대도 동작은 합니다. 그 자리가 왜 그 권한을 가졌는지가 한 달 뒤에 사라질 뿐입니다.

Vite + @crxjs/vite-plugin

vite.config.ts에는 crx({ manifest })가 들어있습니다. plugin이 manifest를 읽어 entry point를 자동으로 결정합니다. content_scripts, background.service_worker, action.default_popup, options_page가 모두 vite의 빌드 입력으로 잡힙니다.

그래서 vite는 src의 React/TS 코드를 일반 웹 빌드처럼 컴파일하면서, 동시에 manifest가 가리키는 모든 진입점을 처리합니다. 진입점 추가는 manifest 한 곳만 손대면 끝납니다.

dev에서 변경 감지

pnpm run dev

vite dev server가 뜨고, crxjs HMR이 진입점별로 다른 전략을 씁니다.

• popup, options: 일반 vite HMR. 저장하면 즉시 반영
• content_script: 새 빌드가 떨어지면 chrome이 자동 reinject. 페이지 새로고침은 필요할 수 있음
• background service worker: 코드가 바뀌면 worker 자체가 죽고 재기동

chrome://extensions의 “Reload” 버튼은 거의 누를 일이 없습니다. 권한을 새로 추가했거나 manifest 구조가 크게 바뀐 경우에만 필요합니다.

build와 package

pnpm run build      # dist/ 에 production 빌드
pnpm run package    # packages/extension.zip 으로 묶기

pnpm run build는 dist/에 production 빌드를 떨굽니다. manifest.json도 같이 생성됩니다. 이 상태로 chrome의 “Load unpacked”로 곧장 띄울 수 있습니다.

pnpm run package는 그 dist를 zip으로 묶어 packages/extension.zip 같은 자리에 떨굽니다. zip 안의 구조는 dist와 동일합니다.

둘이 갈린 이유는 용도가 다르기 때문입니다. build는 개발자가 자기 chrome에 띄울 때, package는 동료에게 zip을 건네거나 Web Store에 업로드할 때 씁니다.

자동화가 멈추는 자리

pnpm run package로 zip이 떨어진 자리가 base 자동화의 끝입니다. 그 다음에 누구에게 보낼지, 어디에 호스팅할지, .pem 키를 어디에 둘지, Chrome Web Store에 등록할지는 도구가 손을 떼는 영역입니다. build-and-package 스킬이 zip 옆에 같이 떨구는 DISTRIBUTION.md도 결정용 메모일 뿐, 자동으로 누군가에게 보내거나 어딘가로 올리지 않습니다.

이 경계는 의도된 것입니다. 키 파일과 스토어 콘솔과 사내 정책 서버는 사용자 자격으로 행동해야 닿는 자리고, 자동화가 그 선을 넘으면 키 유출과 검수 사고가 뒤따릅니다. 다음 절에서 셋의 트레이드오프와 키 관리 절차를 봅니다.

다음

다음 섹션은 distribution입니다. zip 직접 배포, Web Store 업로드, self-host .crx와 update_url 셋의 트레이드오프와, .pem 키 관리 그리고 chrome이 외부 .crx를 차단하는 자리를 어떻게 우회하는지를 봅니다.