개발과 릴리스

이 문서는 실제 확장 프로젝트 C:\Users\Administrator\Desktop\repo\flick를 기준으로 합니다.

요구 환경

Vite 8을 사용하므로 Node는 최신 LTS 계열을 권장합니다. 현재 프로젝트 의존성은 TypeScript와 Vite만으로 단순하게 유지되어 있습니다.

npm install

개발 빌드

npm run dev

이 명령은 vite build --watch를 실행합니다. 소스가 바뀔 때마다 content/bundle.js와 content/bundle.css가 갱신됩니다.

Chrome에서 확인할 때는 chrome://extensions를 열고 개발자 모드를 켠 뒤 content 폴더를 압축해제된 확장 프로그램으로 로드합니다.

프로덕션 빌드

npm run build

현재 빌드 순서는 아래와 같습니다.

1. scripts/bump-extension-version.cjs
2. tsc --noEmit
3. vite build
4. scripts/verify-extension.cjs

버전 동기화

bump-extension-version.cjs는 Chrome Web Store 페이지에서 현재 게시 버전을 읽습니다.

로컬 content/manifest.json 버전이 Store 버전보다 낮거나 같으면 Store 버전의 다음 패치 버전으로 올립니다. 로컬 버전이 이미 더 높으면 유지합니다.

dry-run

버전 변경만 미리 확인하고 싶다면 스크립트를 직접 --dry-run으로 실행할 수 있습니다.

node scripts/bump-extension-version.cjs --dry-run

Manifest 검증

verify-extension.cjs는 manifest가 참조하는 파일이 실제로 존재하는지 검사합니다.

검증 대상은 다음과 같습니다.

• content_scripts[].js
• content_scripts[].css
• icons
• action.default_popup
• action.default_icon
• options_page

Manifest 정책

FLICK은 Manifest v3 확장입니다.

항목	현재 값
manifest_version	3
permissions	[]
content_scripts.run_at	document_idle
action.default_popup	popup.html
options_page	options.html

외부 서버로 게시글 데이터를 보내지 않고, 지원 도메인에서만 content script를 삽입합니다.

새 사이트 규칙 추가

1. src/rules/{site}.ts 파일을 만듭니다.
2. Rule 객체를 export 합니다.
3. match에는 지원 도메인 범위를, articleMatch에는 게시글 URL 패턴을 둡니다.
4. extract()에서 ExtractResult를 반환합니다.
5. src/rules/index.ts의 rules 배열에 등록합니다.
6. 대상 페이지 콘솔에서 FLICK.extractPost()로 결과를 확인합니다.

필요하면 사이트별 훅을 추가할 수 있습니다.

Hook	용도
prePrepare	원본 페이지의 비디오 일시정지 같은 사전 처리
postShortsMounted	쇼츠 패널 삽입 후 자동재생, loop, mute 같은 후처리

콘솔 디버깅

지원 페이지에서 아래 API를 사용할 수 있습니다.

FLICK.isSupportedArticle();
FLICK.getActiveSiteConfig();
FLICK.extractPost();
FLICK.buildUI(FLICK.extractPost());
FLICK.closeShorts();

extractPost() 결과의 status, message, siteId, sourceUrl을 보면 빈 상태나 오류 상태를 빠르게 확인할 수 있습니다.