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는 각각 별도의 디버깅 콘솔을 가진다.

현재글Make Chrome Extension - manifest.json

개발에 대한 지식을 공유하고 기록하기 위한 블로그입니다.

Next.js, react.js, 리액트를 다루는 기술, JavaScript, php, React, Typescript Study, React Test, Cleancode, 리액트, 개발자북클럽, 노마드코더, 타입스크립트, TypeScript, 자바스크립트, TDD, SQL, Git, 타입스크립트 스터디, 클린코드,

Today :
Yesterday :

일	월	화	수	목	금	토
		1	2	3	4	5
6	7	8	9	10	11	12
13	14	15	16	17	18	19
20	21	22	23	24	25	26
27	28	29	30

개발 일지

Make Chrome Extension - manifest.json

'Frontend'의 다른글

티스토리툴바