Chrome Extension Developer Guide [Beginners Friendly]

Getting Started

Build your first browser extension in minutes

What You'll Need

A text editor (VS Code, Sublime Text, or Atom recommended)
Basic knowledge of HTML, CSS, and JavaScript
Chrome, Firefox, or Edge browser for testing
Developer account on the extension store (for publishing)

Step 1: Create Your Project Structure

Create a new directory for your extension with the following structure:

my-extension/
├── manifest.json
├── popup.html
├── popup.js
├── popup.css
├── background.js
├── content.js
└── icons/
    ├── icon16.png
    ├── icon48.png
    └── icon128.png

Step 2: Create the Manifest File

The manifest.json file is the blueprint of your extension. Here's a basic example:

{
  "manifest_version": 3,
  "name": "My First Extension",
  "version": "1.0.0",
  "description": "A simple browser extension",
  "icons": {
    "16": "icons/icon16.png",
    "48": "icons/icon48.png",
    "128": "icons/icon128.png"
  },
  "action": {
    "default_popup": "popup.html",
    "default_icon": "icons/icon48.png"
  },
  "permissions": ["storage", "activeTab"],
  "background": {
    "service_worker": "background.js"
  },
  "content_scripts": [{
    "matches": [""],
    "js": ["content.js"]
  }]
}

Step 3: Build Your Popup Interface

Create popup.html for the extension's user interface:

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="popup.css">
</head>
<body>
  <div class="container">
    <h1>My Extension</h1>
    <button id="actionBtn">Click Me</button>
    <p id="result"></p>
  </div>
  <script src="popup.js"></script>
</body>
</html>

Step 4: Load Your Extension

Chrome/Edge:

1. Open chrome://extensions/ or edge://extensions/
2. Enable "Developer mode"
3. Click "Load unpacked"
4. Select your extension directory

Firefox:

1. Open about:debugging
2. Click "This Firefox"
3. Click "Load Temporary Add-on"
4. Select your manifest.json file

Manifest File

Understanding the extension configuration

Essential Fields

manifest_version

Specifies the manifest file format. Use version 3 for modern extensions.

"manifest_version": 3

name

The name of your extension (maximum 45 characters).

"name": "My Awesome Extension"

version

Version string with up to four numbers separated by dots.

"version": "1.0.0"

description

A short description (maximum 132 characters).

"description": "Boost productivity with this tool"

Permissions

Request permissions your extension needs:

Permission	Description
activeTab	Access the current active tab
storage	Use chrome.storage API
tabs	Access tabs API for tab management
notifications	Display notifications to users
webRequest	Intercept and modify web requests
cookies	Access and modify cookies

Important

Only request permissions your extension actually needs. Excessive permissions may deter users from installing.

API Reference

Common APIs and their usage

Chrome Storage API

Store and retrieve data across browser sessions with Free Chrome Extension API:

// Save data
chrome.storage.sync.set({ key: 'value' }, function() {
  console.log('Data saved');
});

// Retrieve data
chrome.storage.sync.get(['key'], function(result) {
  console.log('Value is: ' + result.key);
});

// Remove data
chrome.storage.sync.remove('key', function() {
  console.log('Data removed');
});

Tabs API

Interact with browser tabs:

// Get current tab
chrome.tabs.query({active: true, currentWindow: true}, function(tabs) {
  let currentTab = tabs[0];
  console.log(currentTab.url);
});

// Create new tab
chrome.tabs.create({ url: 'https://example.com' });

// Update tab
chrome.tabs.update(tabId, { url: 'https://newurl.com' });

// Close tab
chrome.tabs.remove(tabId);

Runtime API

Handle extension lifecycle events:

// Listen for installation
chrome.runtime.onInstalled.addListener(function(details) {
  if(details.reason == "install"){
    console.log("Extension installed!");
  }
});

// Send message between scripts
chrome.runtime.sendMessage({type: "getData"}, function(response) {
  console.log(response);
});

// Listen for messages
chrome.runtime.onMessage.addListener(function(request, sender, sendResponse) {
  if (request.type === "getData") {
    sendResponse({data: "Hello from background"});
  }
});

Notifications API

Display desktop notifications:

chrome.notifications.create({
  type: 'basic',
  iconUrl: 'icon48.png',
  title: 'Notification Title',
  message: 'This is the notification message',
  priority: 2
});

UI Design Guidelines

Create beautiful and intuitive interfaces

Popup Design Best Practices

Do

Keep popups under 800x600 pixels
Use clear, readable fonts (14px minimum)
Provide immediate visual feedback
Use consistent color schemes
Include loading states

Don't

Don't make popups too large
Avoid tiny text or buttons
Don't use too many colors
Avoid complex animations
Don't hide important features

Icon Requirements

Size	Purpose	Format
16x16	Favicon and extension menu	PNG
48x48	Extension management page	PNG
128x128	Chrome Web Store listing	PNG

Color Scheme Recommendations

#3B82F6

Primary Blue

#8B5CF6

Primary Purple

#10B981

Success Green

#EF4444

Error Red

Testing Your Extension

Ensure quality before publishing

Testing Checklist

Functionality Testing

Test all features and user interactions work as expected

Cross-Browser Testing

Test on Chrome, Firefox, and Edge browsers

Permission Testing

Verify all requested permissions are used correctly

Performance Testing

Ensure extension doesn't slow down the browser

Security Testing

Check for XSS vulnerabilities and secure data handling

UI/UX Testing

Verify interface is intuitive and responsive

Debugging Tips

// Add console logs for debugging
console.log('Extension loaded');

// Use debugger statement
debugger;

// Check background script errors
chrome://extensions/ > Details > Inspect views: background page

// Debug content scripts
Right-click page > Inspect > Console tab

// View storage data
chrome://extensions/ > Details > Storage

Publishing Your Extension

Submit to extension stores

Pre-Publishing Requirements

Store Assets

• 128x128 icon
• 440x280 screenshot
• 1280x800 promotional image

Documentation

• Detailed description
• Privacy policy
• Support email

Compliance

• Store policies review
• Security audit
• Terms of service

Submission Process

1

Create Developer Account

Register on Chrome Web Store, Firefox Add-ons, or Edge Add-ons. One-time fee may apply.

2

Prepare Extension Package

Zip your extension directory (excluding hidden files and development files).

3

Upload & Configure

Upload your zip file and fill in store listing details, screenshots, and metadata.

4

Review Process

Wait for store review (typically 1-3 days). Address any feedback if rejected.

5

Publish & Promote

Once approved, your extension goes live. Promote it to reach your target audience.

Pro Tip

Submit to multiple stores simultaneously to maximize reach. Each store has different audiences and requirements.

Best Practices

Build better, more secure extensions

Security

Use Content Security Policy (CSP)
Sanitize all user inputs
Use HTTPS for all external requests
Avoid eval() and inline scripts
Encrypt sensitive data

Performance

Minimize DOM manipulation
Use debouncing for frequent events
Lazy load resources when possible
Compress images and assets
Use background workers efficiently

User Experience

Provide clear error messages
Include keyboard shortcuts
Support dark mode
Make UI accessible (ARIA labels)
Provide helpful onboarding

Code Quality

Use version control (Git)
Write modular, reusable code
Comment complex logic
Follow consistent naming conventions
Keep dependencies up to date

Code Examples

Ready-to-use snippets and templates

Complete Extension Template

Simple Popup Extension

popup.html

<!DOCTYPE html>
<html>
<head>
  <style>
    body { width: 300px; padding: 20px; font-family: Arial; }
    button { width: 100%; padding: 10px; background: #8B5CF6; 
             color: white; border: none; border-radius: 5px; 
             cursor: pointer; font-size: 16px; }
    button:hover { background: #7C3AED; }
  </style>
</head>
<body>
  <h2>My Extension</h2>
  <button id="clickBtn">Click Me</button>
  <p id="output"></p>
  <script src="popup.js"></script>
</body>
</html>

popup.js

document.getElementById('clickBtn').addEventListener('click', function() {
  chrome.tabs.query({active: true, currentWindow: true}, function(tabs) {
    let currentTab = tabs[0];
    document.getElementById('output').textContent = 
      'Current URL: ' + currentTab.url;
  });
});

Content Script Injection

// content.js - Runs on web pages
console.log('Content script loaded');

// Modify page content
document.body.style.backgroundColor = '#f0f0f0';

// Listen for messages from background/popup
chrome.runtime.onMessage.addListener(function(request, sender, sendResponse) {
  if (request.action === 'changeColor') {
    document.body.style.backgroundColor = request.color;
    sendResponse({status: 'Color changed'});
  }
});

Background Service Worker

// background.js - Runs in the background
chrome.runtime.onInstalled.addListener(() => {
  console.log('Extension installed');
  
  // Create context menu
  chrome.contextMenus.create({
    id: 'myContextMenu',
    title: 'My Extension Action',
    contexts: ['selection']
  });
});

// Handle context menu clicks
chrome.contextMenus.onClicked.addListener((info, tab) => {
  if (info.menuItemId === 'myContextMenu') {
    console.log('Selected text: ' + info.selectionText);
  }
});

// Listen for tab updates
chrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) => {
  if (changeInfo.status === 'complete') {
    console.log('Page loaded: ' + tab.url);
  }
});

Options Page

options.html

<!DOCTYPE html>
<html>
<body>
  <h1>Extension Options</h1>
  <label>
    <input type="checkbox" id="enableFeature">
    Enable Feature
  </label>
  <button id="saveBtn">Save</button>
  <script src="options.js"></script>
</body>
</html>

options.js

// Load saved settings
chrome.storage.sync.get(['enableFeature'], function(result) {
  document.getElementById('enableFeature').checked = result.enableFeature || false;
});

// Save settings
document.getElementById('saveBtn').addEventListener('click', function() {
  const enabled = document.getElementById('enableFeature').checked;
  chrome.storage.sync.set({enableFeature: enabled}, function() {
    alert('Settings saved!');
  });
});

Developer Guide