Make Chrome Extension - manifest.json

Frontend

Make Chrome Extension - manifest.json

rachel_13 2025. 4. 7. 20:06

🧠 크롬 익스텐션 구조 개념 정리

크롬 익스텐션은 기본적으로 웹 기술로 만들 수 있는 작은 앱이다.

기본적인 구성 요소는 다음과 같다.

- mainfest.json : 익스텐션 설정 파일 (필수) (이 파일이 있어야 크롬 익스텐션으로 인식할 수 있다.)

- popup : 크롬 툴바에서 아이콘을 클릭하면 나오는 UI

- background script : 백그라운드에서 계속 동작하는 JS

- content script : 웹 페이지에 삽입되는 JS

- options page : 사용자 설정 페이지

- permissions : 어떤 기능을 사용할지 설정 (예: 탭 접근, 스토리지)

예시)

{
  "manifest_version": 3, // 버전 3 사용 (버전 2는 지원 종료)
  "name": "My First Extension", // 익스텐션 이름
  "version": "0.1.0", // 현재 버전 (앱 처럼 관리됨)
  "description": "This is a beginner-friendly Chrome extension.", // 익스텐션 설명
  "icons": { // 확장 프로그램 아이콘 파일 경로
    "16": "assets/icon-16.png",
    "48": "assets/icon-48.png",
    "128": "assets/icon-128.png"
  },
  "action": { // 크롬 툴바에서 클릭했을 때 나오는 팝업 설정
    "default_popup": "src/popup.html", // 아이콘 클릭 시 표시될 HTML 파일 경로
    "default_icon": "assets/icon-48.png" // 아이콘 파일 경로
  },
  "background": { 
    "service_worker": "src/background.js" // 백그라운드에서 계속 실행되는 스크립트
  },
  "permissions": ["storage", "tabs"], // 익스텐션이 사용하려는 기능들
  // storage: 데이터 저장 , tabs: 탭 조작
  "host_permissions": ["https://example.com/*"], // 특정 도메인 접근 권한 설정
  "content_scripts": [ // 웹 페이지에 삽입되는 JS 설정
    {
      "matches": ["https://*/*"], // 어떤 URL에서 콘텐츠 스크립트를 실행할지 명시
      "js": ["src/content.js"] // 실행할 자바스크립트 파일 경로
    }
  ]
}

🧩 왜 popup.html을 써야 할까?

나는 React 로 프로젝트를 생성했기 때문에, 내 경우 src/Popup.tsx 안에 팝업 컴포넌트를 작성해두었다.

그런데, 크롬 익스텐션은 default_popup에 HTML 파일 경로만 받을 수 있다고 한다.

React 컴포넌트(popup.tsx)는 브라우저가 직접 이해할 수 없기 때문에, 반드시 HTML로 감싸줘야 한다.

즉, popup.tsx는 직접 넣을 수 없고,

"action": {
  "default_popup": "popup.html"
}

이런 식으로 써야 하고, popup.html 안에서 React 앱(popup.tsx)을 마운트하는 방식으로 해결할 수 있다.

📁 구조 예시

src/
├── popup.tsx
├── popup.html

popup.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Popup</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/popup.tsx"></script>
  </body>
</html>

popup.tsx

import React from 'react'
import ReactDOM from 'react-dom/client'

function Popup() {
  return <div className="text-xl text-blue-500">Hello from Popup!</div>
}

const root = document.getElementById('root')!
ReactDOM.createRoot(root).render(<Popup />)

🛠 Vite 설정 팁

Vite는 기본적으로 index.html을 기준으로 작동하지만, 여러 개의 entry HTML을 만들 수 있다.

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { resolve } from 'path'

export default defineConfig({
  plugins: [react()],
  build: {
    rollupOptions: {
      input: {
        popup: resolve(__dirname, 'src/popup.html'),
        // background 스크립트나 content script는 entry만 등록해줘도 됨
      },
      output: {
        // 폴더 구조 깔끔하게 정리하고 싶다면 여기서 조정
      }
    },
    outDir: 'dist',
  },
})

🚀 디버깅 하는 방법

📌 가이드

- 리액트로 개발하고 있다면, build 후, dist/ 폴더에도 manifest.json을 복사한다.

- 크롬 주소창에 chrome://extensions를 입력한다.

- "개발자 모드"를 활성화한다.

- "압축해제된 확장 프로그램을 로드합니다" 버튼을 클릭한다. (Load unpacked 버튼 클릭)
- 프로젝트 폴더를 선택한다. (로컬 디바이스의 dist 폴더 경로를 찾아서 업로드해 준다. )
- 정상적으로 로드되었다면 툴바에 아이콘이 나타날 것이다.

📌 참고 사항

background와 content_scripts는 각각 별도의 디버깅 콘솔을 가진다.