Chrome Extension Template 🚀

Read this in other languages: 日本語

A lightweight and accessible template for easily developing modern Chrome extensions

📋 Table of Contents

• Features
• File Structure
• Installation
• Usage
• Customization Guide
• Development Tips
• How to Contribute
• Technical Specifications
• Todo

Features 💯

🌙 ⟷ ☀️ Theme Support	🔄 Auto-Save	🛡️ Minimal Permissions
📦 Data Management	♿ Accessible UI	🔌 Manifest V3

• Manifest V3 Compatible: Uses an event-driven extension service worker
• Minimal Permissions: Requests only storage and no default site access
• Modular Design: Separates shared settings, popup, options, background, and optional examples
• Theme Support: Supports system, light, and dark themes
• Data Management: Imports and exports validated settings backups
• Auto-Save Functionality: Saves and synchronizes settings in real time
• Accessible UI: Includes semantic controls, visible focus, and 44px interaction targets
• Zero Dependencies: Uses browser and Node.js built-in APIs only

File Structure 📁

Chrome-Extension-Template/
│
├── manifest.json              # Extension configuration
│
├── shared/
│   ├── settings.js            # Settings schema and storage helpers
│   ├── ui.js                  # Theme and localization helpers
│   └── ui.css                 # Shared accessible UI styles
│
├── scripts/
│   ├── background.js          # Extension service worker
│   ├── validate.mjs           # Source and configuration checks
│   └── build.mjs              # Runtime-only build script
│
├── popup/                     # Toolbar popup
├── options/                   # Extension options page
├── _locales/                  # English and Japanese messages
├── examples/content-script/   # Optional page-access example
├── tests/                     # Node.js built-in tests
│
└── assets/
    └── icons/                 # 16, 48, and 128px icon files

System Architecture 🔄

Component	Role	Features
🔄 Service Worker	Event Processing	Installation, startup, and badge updates
🖥️ Popup UI	Quick Settings	Enable/disable control and status display
⚙️ Options UI	Detailed Settings	Theme, badge, backup, and reset controls
💾 Chrome Storage	Data Storage	Synchronized settings persistence

⚙️ Component Interaction Flow ⚙️

Popup UI ⟷ Shared Settings ⟷ Chrome Storage
⬆️ ⬇️
Options UI ⟷ Shared Settings
⬆️ ⬇️
Service Worker ⟷ Chrome Action

The base template does not inject code into web pages. A narrowly scoped content-script example is available in examples/content-script/ when page access is required.

Installation 🔧

Requirements

• Google Chrome 102 or later
• Developer mode enabled
• Node.js 20 or later only when running tests or builds

Steps

1. Clone the repository:

   git clone https://github.com/E20C1/Chrome-Extension-Template.git
   cd Chrome-Extension-Template

2. Load the extension in Chrome:

   • Open chrome://extensions in Chrome
   • Turn on Developer mode
   • Click Load unpacked
   • Select the cloned directory

🔍	Access chrome://extensions
🔧	Turn on "Developer mode" in the top right
📦	Click "Load unpacked" and select the repository
✅	Verify the extension has loaded successfully

Usage 👆

Basic Features

• Enable/Disable Extension: Toggle the extension state from the popup
• Theme Switching: Select system, light, or dark mode on the options page
• Status Badge: Show or hide the ON / OFF toolbar badge
• Automatic Saving: Apply and synchronize every settings change immediately

Data Management

• Export Settings: Download the current settings as a versioned JSON backup
• Import Settings: Restore a validated JSON backup up to 256KB
• Reset Settings: Restore safe defaults after confirmation

Customization Guide 🛠️

Editing Extension Information

Update these messages in both _locales/en/messages.json and _locales/ja/messages.json:

{
  "extensionName": { "message": "Your Extension Name" },
  "extensionDescription": { "message": "Your extension description" },
  "actionTitle": { "message": "Open Your Extension" }
}

Permission Settings

Add only permissions required by a current feature to respect user privacy:

"permissions": [
  "storage"
]

For page access, start with examples/content-script/README.md and use the narrowest possible match pattern. Do not add <all_urls> for future or hypothetical features.

Adding Settings

1. Add a default value and normalization rule to shared/settings.js
2. Add localized labels to both locale files
3. Add a semantic control to the popup or options page
4. Add or update a test in tests/

Adding Icons

Add icons of the following sizes to the assets/icons/ directory:

• icon16.png (16x16 px)
• icon48.png (48x48 px)
• icon128.png (128x128 px)

Key Features ✨

• Simple Design: Easy-to-understand structure for beginners
• Minimal Permissions: No host or tab access in the base template
• Modern UI: Responsive popup and single-column options layout
• Fast Performance: No frameworks, remote assets, or runtime dependencies
• Accessible Foundation: Keyboard focus, reduced motion, forced colors, and localized labels

Development Tips 💡

1. Run Checks: Use npm test to validate settings, Manifest, i18n, HTML, CSS, and icons
2. Create a Build: Use npm run build to copy runtime files into dist/
3. Reload Changes: Use the refresh button on chrome://extensions
4. Debug the Worker: Open the service worker inspector from the extension details page
5. Inspect Storage: Settings are stored in chrome.storage.sync

npm test
npm run build

GitHub Actions runs the same checks for every push and pull request.

How to Contribute 🤝

1. Fork the repository 🍴
2. Add a focused feature or improvement ✨
3. Run the tests and build locally ✅
4. Submit a pull request 🚀

Contribution Guidelines:

• Follow the existing code style 📏
• Request only permissions required by the feature 🛡️
• Write clear commit messages 📝
• Explain the reason and impact of each change 🔍

Technical Specifications 💻

• Manifest Version: Manifest V3
• Minimum Chrome Version: Chrome 102
• JavaScript: Standard ES modules and modern browser APIs
• Service Worker: Event-driven background processing
• Storage API: chrome.storage.sync restricted to trusted extension contexts
• Internationalization: Chrome i18n with English and Japanese locales
• Dependencies: No runtime or npm package dependencies
• Build Output: Runtime-only files in dist/

Todo 📝

• Add icon files
• Add unit tests and source validation
• Set up build automation and GitHub Actions
• Add an optional onboarding-page example
• Add cross-browser packaging examples
• Add automated end-to-end extension tests

License 📄

MIT License

---

© 2026 Chrome Extension Template
Made with ❤️ by E20C1