Chrome Extension Hello World

June 01, 2025 · 11 min read · tutorial

Building your first Chrome extension is easier than you think. In this comprehensive guide, we’ll walk through creating a basic extension from scratch, understanding each component, and getting it running in your browser. This tutorial is designed for complete beginners with no prior extension development experience.

Prerequisites

Before we begin, ensure you have the following:

Google Chrome installed on your computer
A basic text editor (VS Code, Sublime Text, or Notepad++)
Basic understanding of HTML, CSS, and JavaScript
A desire to learn something new!

That’s it! No special tools or paid software required.

Understanding Chrome Extensions

Chrome extensions are small software programs that customize the browsing experience. They can enhance productivity, modify web pages, provide utilities, and much more. At their core, extensions are just web technologies—HTML, CSS, and JavaScript—packaged in a special way that gives them access to Chrome’s APIs.

Extensions can:

Modify how web pages look and behave
Add new features to Chrome
Communicate with web servers
Store data locally or in the cloud
And much more

Creating Your Project Structure

Every Chrome extension needs a specific file structure. Create a new folder on your computer (let’s call it “my-first-extension”) and add the following files:

manifest.json - The configuration file that tells Chrome about your extension
popup.html - The interface users see when clicking your extension icon
popup.js - JavaScript for handling user interactions
popup.css - Styling for your popup interface
icon.png - A 128x128 pixel icon for your extension (you can use any placeholder image)

Your folder structure should look like this:

my-first-extension/
├── manifest.json
├── popup.html
├── popup.js
├── popup.css
└── icon.png

Setting Up Your Development Environment

Create a dedicated folder for your extension projects. Within that folder, create another folder called “my-first-extension”. This keeps your work organized and makes it easier to manage multiple extension projects.

Understanding the Manifest File

The manifest.json is the heart of your extension. It’s the only required file and tells Chrome everything it needs to know about your extension. Here’s the minimum required structure:

{
  "manifest_version": 3,
  "name": "My First Extension",
  "version": "1.0",
  "description": "A simple Chrome extension tutorial",
  "action": {
    "default_popup": "popup.html",
    "default_icon": "icon.png"
  }
}

Let’s break down each field:

manifest_version: 3 is the latest version of Chrome’s extension platform. Always use version 3 for new extensions.
name: The name users will see in the Chrome Web Store and in their extension list
version: Your extension’s version number (follows semantic versioning)
description: A brief description of what your extension does
action: Defines the popup that appears when clicking the extension icon

The manifest_version: 3 refers to Manifest V3, the latest version of Chrome’s extension platform. This version includes improved security features, more efficient background processing, and better performance.

Let’s create a simple popup that displays a greeting and responds to user interaction:

popup.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My First Extension</title>
  <link rel="stylesheet" href="popup.css">
</head>
<body>
  <div class="container">
    <img src="icon.png" alt="Extension Icon" class="icon">
    <h1>Hello, World!</h1>
    <p>Welcome to my first Chrome extension.</p>
    <button id="clickMe" class="btn">Click Me</button>
    <div id="result" class="result hidden"></div>
  </div>
  <script src="popup.js"></script>
</body>
</html>

popup.css

body {
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
  width: 300px;
  padding: 20px;
  margin: 0;
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
}

.container {
  text-align: center;
}

.icon {
  width: 64px;
  height: 64px;
  border-radius: 50%;
  margin-bottom: 16px;
}

h1 {
  margin: 0 0 8px 0;
  font-size: 24px;
}

p {
  margin: 0 0 16px 0;
  opacity: 0.9;
}

.btn {
  background: white;
  color: #667eea;
  border: none;
  padding: 12px 24px;
  border-radius: 6px;
  font-size: 14px;
  font-weight: bold;
  cursor: pointer;
  transition: transform 0.2s, box-shadow 0.2s;
}

.btn:hover {
  transform: translateY(-2px);
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2);
}

.result {
  margin-top: 16px;
  padding: 12px;
  background: rgba(255, 255, 255, 0.2);
  border-radius: 6px;
}

.result.hidden {
  display: none;
}

popup.js

document.addEventListener('DOMContentLoaded', () => {
  const button = document.getElementById('clickMe');
  const result = document.getElementById('result');
  
  button.addEventListener('click', () => {
    // Get the current tab
    chrome.tabs.query({ active: true, currentWindow: true }, (tabs) => {
      const currentTab = tabs[0];
      
      // Show result
      result.textContent = `You're on: ${currentTab.title}`;
      result.classList.remove('hidden');
      
      // Optional: Send a message to the page
      chrome.tabs.sendMessage(currentTab.id, { 
        action: 'buttonClicked' 
      });
    });
  });
});

Adding Basic Interactivity

Create a content script to demonstrate communication between your popup and web pages:

content.js (create this file)

// This runs on web pages
console.log('Content script loaded!');

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.action === 'buttonClicked') {
    document.body.style.backgroundColor = 
      getRandomColor();
  }
});

function getRandomColor() {
  const colors = [
    '#ff6b6b', '#4ecdc4', '#45b7d1', '#96ceb4', 
    '#ffeaa7', '#dfe6e9', '#a29bfe', '#fd79a8'
  ];
  return colors[Math.floor(Math.random() * colors.length)];
}

Update manifest.json

{
  "manifest_version": 3,
  "name": "My First Extension",
  "version": "1.0",
  "description": "A simple Chrome extension tutorial",
  "action": {
    "default_popup": "popup.html",
    "default_icon": "icon.png"
  },
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["content.js"]
    }
  ],
  "permissions": ["activeTab"]
}

Loading Your Extension

To test your extension:

Open Chrome and navigate to chrome://extensions/
Enable “Developer mode” using the toggle in the top right corner
Click “Load unpacked” and select your extension folder
Your extension icon should appear in the Chrome toolbar (look for your icon next to the address bar)
Click the icon to see your popup in action!
Try clicking the button to see the interaction

Troubleshooting

Popup not showing?

Verify your manifest.json correctly references the popup file
Ensure the file exists in the correct location
Check for any JSON syntax errors in manifest.json

Changes not appearing?

Click the reload button on your extension card in chrome://extensions/
Make sure you’re editing the correct files in the correct folder
Try closing and reopening Chrome

Console errors?

Right-click your popup and select “Inspect” to open developer tools
Check the Console tab for error messages
Verify all file paths in your HTML are correct

Troubleshooting Common Issues

Popup not showing? Make sure your manifest.json correctly references the popup file and that the file exists in the correct location. Check the console for errors.

Changes not appearing? Click the reload button on your extension in chrome://extensions/ to apply changes. Chrome doesn’t automatically reload extension files.

Console errors? Right-click your popup and select “Inspect” to open developer tools and debug any issues. This is the same DevTools you use for regular web pages.

Understanding the Extension Lifecycle

When you load an extension in developer mode, Chrome monitors your files. Any changes you make to your HTML, CSS, or JavaScript files are reflected immediately when you reload the extension. To reload, simply click the refresh icon on your extension card in chrome://extensions/.

The extension lifecycle includes:

Loading: Chrome reads your manifest and registers your files
Activation: Your popup is ready to display when clicked
Execution: Your JavaScript runs when users interact with the popup
Deactivation: Closing the popup terminates JavaScript execution

What’s Next?

Congratulations on building your first Chrome extension! The journey doesn’t end here. Here are exciting topics to explore next:

Content Scripts

Content scripts let you automatically modify web pages. You can:

Change page styling
Remove unwanted elements (ads, popups)
Add new features to existing websites
Extract data from pages

Background Scripts (Service Workers)

Background scripts run independently of any web page:

Handle events when no popup is open
Manage alarms and scheduled tasks
Coordinate between different parts of your extension

Chrome APIs

Chrome provides powerful APIs for:

tabs - Get information about open tabs
bookmarks - Read and modify bookmarks
history - Access browsing history
storage - Store data persistently
notifications - Show system notifications
webNavigation - Track navigation events

Storage API

Learn to persist user preferences:

chrome.storage.sync.set({ theme: 'dark' }, () => {
  console.log('Theme saved');
});

chrome.storage.sync.get(['theme'], (result) => {
  console.log('Current theme:', result.theme);
});

Publishing to the Chrome Web Store

Ready to share your extension with the world?

Create a developer account (one-time $5 fee)
Prepare your extension (add screenshots, description)
Upload your extension package
Submit for review (usually takes 1-3 days)
Publish once approved!

Common Issues and Solutions

Here’s a quick reference for common problems:

Issue	Solution
Popup doesn’t open	Check manifest.json action configuration
Changes not visible	Reload extension in chrome://extensions/
Console errors	Use popup inspection to debug
Permission denied	Add required permissions to manifest
Content script not running	Check matches pattern in manifest

Understanding the Extension Lifecycle

Go to chrome://extensions/
Find your extension
Click the refresh icon (🔄)
Test your changes

This iterative development process makes building extensions fast and enjoyable.

Extension States

Your extension goes through several states:

Development: Loading from folder, hot-reloading
Packed: As a .crx file for testing
Published: Available in Chrome Web Store

Conclusion

You’ve taken your first step into the world of Chrome extensions! This simple foundation opens the door to powerful browser customization. The Chrome extension ecosystem offers endless possibilities for:

Enhancing productivity
Automating repetitive tasks
Creating unique browsing experiences
Building businesses around useful tools

Keep experimenting, and don’t be afraid to look at how other extensions work. The best way to learn is by doing—and now you have the foundation to start building!

Chrome Extension Hello World

Prerequisites

Understanding Chrome Extensions

Creating Your Project Structure

Setting Up Your Development Environment

Understanding the Manifest File

Creating Your First Popup

popup.html

popup.css

popup.js

Adding Basic Interactivity

content.js (create this file)

Update manifest.json

Loading Your Extension

Troubleshooting

Troubleshooting Common Issues

Understanding the Extension Lifecycle

What’s Next?

Content Scripts

Background Scripts (Service Workers)

Chrome APIs

Storage API

Publishing to the Chrome Web Store

Common Issues and Solutions

Understanding the Extension Lifecycle

Extension States

Conclusion