개발과 릴리스

이 문서는 FLICK Chrome 확장 프로젝트의 현재 소스 구조를 기준으로 합니다.

요구 환경

확장 프로젝트는 package.json 기준 TypeScript 6.0.3과 Vite 8.0.16 계열을 사용합니다. Vite 8을 사용하므로 Node는 최신 LTS 계열을 권장합니다.

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
version	0.0.7
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을 보면 빈 상태나 오류 상태를 빠르게 확인할 수 있습니다.