Build a Focus Mode Chrome Extension: Complete Development Guide
In an era where digital distractions compete for our attention every few seconds, the ability to maintain focused work sessions has become a rare and valuable skill. Whether you are a developer deep in code, a writer crafting the next great novel, or a student preparing for important exams, the constant ping of notifications and the temptation of social media can significantly impact your productivity. Building a focus mode extension for Chrome provides a powerful solution to these challenges, giving you complete control over your browsing environment and helping you achieve deep work states that lead to superior outcomes.
This comprehensive guide walks you through the complete process of creating a professional-grade distraction blocker chrome extension using Manifest V3. You will learn how to implement website blocking, create customizable focus sessions, build beautiful user interfaces, and integrate advanced features that make your extension stand out in the Chrome Web Store. By the end of this tutorial, you will have a fully functional deep work extension that can transform your browsing experience and dramatically improve your productivity.
Understanding Focus Mode and Distraction Blocking
Before writing any code, it is essential to understand what makes an effective focus mode extension and why these tools have become essential for knowledge workers in the digital age. The core concept behind a focus mode extension is simple: provide users with mechanisms to eliminate or reduce access to distracting websites during designated work periods. However, implementing this seemingly straightforward feature requires careful consideration of user experience, privacy concerns, and the technical limitations of Chrome’s extension architecture.
Modern focus mode extensions must address several key requirements to be genuinely useful. First, they need robust website blocking capabilities that can prevent access to specific URLs or domain categories. Second, they require customizable timers that allow users to define their ideal focus session lengths. Third, they should provide clear visual feedback about the current focus state and remaining time. Fourth, they need to handle edge cases gracefully, such as what happens if a user accidentally closes the extension popup during an active session. Finally, they should offer configuration options that let users tailor the blocking behavior to their specific needs and workflows.
The psychological foundation behind these extensions lies in the concept of “implementation intentions” - the idea that by pre-committing to avoid certain behaviors (like checking social media), users can conserve willpower and maintain focus more effectively. A well-designed distraction blocker chrome extension essentially externalizes this commitment, making it easier for users to stick to their productivity goals.
Project Architecture and File Structure
Every Chrome extension project benefits from a well-organized file structure that separates concerns and makes the codebase maintainable as features grow more complex. For our focus mode extension, we will organize the project with the following directory structure that follows Chrome’s recommended practices.
The root directory contains the manifest.json file, which serves as the configuration blueprint for the entire extension. The popup directory houses the HTML, CSS, and JavaScript files for the extension’s user interface. The background directory contains the service worker code that runs independently of the popup and manages the core blocking logic. Finally, the icons directory stores the extension’s icon graphics in various sizes required by the Chrome Web Store.
This separation of concerns is particularly important for focus mode extensions because the background service worker must maintain the blocking state even when no popup window is open. Without this architectural separation, users might find ways to circumvent the blocking by closing the extension popup.
Creating the Manifest V3 Configuration
Every Chrome extension begins with its manifest.json file, which defines the extension’s capabilities, permissions, and components. For our focus mode extension, we need to specify several key permissions and declare the various files that make up our extension.
{
"manifest_version": 3,
"name": "Focus Mode Pro",
"version": "1.0.0",
"description": "A distraction blocker chrome extension for deep work sessions. Block distracting websites, set focus timers, and achieve more with built-in productivity features.",
"permissions": [
"storage",
"alarms",
"notifications"
],
"host_permissions": [
"<all_urls>"
],
"action": {
"default_popup": "popup/popup.html",
"default_icon": {
"16": "icons/icon16.png",
"48": "icons/icon48.png",
"128": "icons/icon128.png"
}
},
"background": {
"service_worker": "background/background.js"
},
"icons": {
"16": "icons/icon16.png",
"48": "icons/icon48.png",
"128": "icons/icon128.png"
}
}
This manifest configuration declares the permissions our extension needs to function properly. The storage permission allows us to save user preferences and settings persistently. The alarms permission enables us to schedule notifications and manage focus session timing. The notifications permission lets us alert users when focus sessions end. The host_permissions with “
One important consideration for Manifest V3 is the distinction between host permissions and other permissions. In newer versions of Chrome, host permissions must be specified separately and are more restrictive. Our configuration places them in the host_permissions array, which is the correct approach for extensions that need to block content across multiple websites.
Building the Background Service Worker
The background service worker is the heart of our focus mode extension, responsible for managing the blocking state, handling timers, and coordinating between different parts of the extension. This script runs independently of any open popup window, ensuring that blocking remains active even when users are not actively interacting with the extension.
// background/background.js
// State management for focus mode
let focusState = {
isActive: false,
endTime: null,
blockedSites: [],
focusDuration: 25 // minutes
};
// Initialize extension state from storage
chrome.storage.local.get(['focusState'], (result) => {
if (result.focusState) {
focusState = result.focusState;
// Restore active session if it was interrupted
if (focusState.isActive && focusState.endTime) {
const now = Date.now();
if (now < focusState.endTime) {
startBlocking();
} else {
// Session has expired, reset state
resetFocusState();
}
}
}
});
// Message handler for communication with popup
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
switch (message.type) {
case 'START_FOCUS':
startFocusSession(message.duration, message.blockedSites);
sendResponse({ success: true, state: focusState });
break;
case 'STOP_FOCUS':
stopFocusSession();
sendResponse({ success: true, state: focusState });
break;
case 'GET_STATE':
sendResponse({ state: focusState });
break;
case 'UPDATE_BLOCKED_SITES':
focusState.blockedSites = message.blockedSites;
saveState();
if (focusState.isActive) {
startBlocking();
}
sendResponse({ success: true });
break;
}
return true;
});
function startFocusSession(duration, blockedSites) {
focusState.isActive = true;
focusState.focusDuration = duration;
focusState.blockedSites = blockedSites || focusState.blockedSites;
focusState.endTime = Date.now() + (duration * 60 * 1000);
saveState();
startBlocking();
// Schedule end notification
chrome.alarms.create('focusEnd', {
delayInMinutes: duration
});
}
function stopFocusSession() {
resetFocusState();
chrome.alarms.clear('focusEnd');
}
function resetFocusState() {
focusState.isActive = false;
focusState.endTime = null;
saveState();
stopBlocking();
}
function startBlocking() {
// Use declarativeNetRequest for content blocking
// This requires a ruleset file (handled separately)
console.log('Starting focus mode blocking for:', focusState.blockedSites);
}
function stopBlocking() {
console.log('Stopping focus mode blocking');
}
function saveState() {
chrome.storage.local.set({ focusState });
}
// Handle alarm for focus session end
chrome.alarms.onAlarm.addListener((alarm) => {
if (alarm.name === 'focusEnd') {
showFocusEndNotification();
resetFocusState();
}
});
function showFocusEndNotification() {
chrome.notifications.create({
type: 'basic',
iconUrl: 'icons/icon128.png',
title: 'Focus Session Complete',
message: 'Great work! Your focus session has ended. Take a break before starting another session.',
priority: 1
});
}
This background service worker implements the core logic for managing focus sessions. It maintains the extension’s state in Chrome’s local storage, allowing the state to persist across browser restarts and extension updates. The message listener handles communication between the popup and the background worker, enabling the user interface to control the focus session lifecycle.
The implementation uses Chrome’s alarms API for scheduling the end of focus sessions, which is more reliable than using setTimeout because it continues working even when the extension’s service worker has been terminated due to inactivity. This is particularly important for longer focus sessions that might span several hours.
Creating the Declarative Net Request Rules
For Manifest V3, content blocking is handled through the Declarative Net Request API, which provides a more privacy-friendly way to block network requests compared to the older webRequest API. This approach allows extensions to specify blocking rules without needing to observe or modify the actual content of web requests.
First, we need to create a ruleset file that defines the blocking rules:
[
{
"id": 1,
"priority": 1,
"action": {
"type": "block"
},
"condition": {
"urlFilter": "facebook.com",
"resourceTypes": ["main_frame"]
}
},
{
"id": 2,
"priority": 1,
"action": {
"type": "block"
},
"condition": {
"urlFilter": "twitter.com",
"resourceTypes": ["main_frame"]
}
},
{
"id": 3,
"priority": 1,
"action": {
"type": "block"
},
"condition": {
"urlFilter": "instagram.com",
"resourceTypes": ["main_frame"]
}
},
{
"id": 4,
"priority": 1,
"action": {
"type": "block"
},
"condition": {
"urlFilter": "youtube.com",
"resourceTypes": ["main_frame"]
}
},
{
"id": 5,
"priority": 1,
"action": {
"type": "block"
},
"condition": {
"urlFilter": "reddit.com",
"resourceTypes": ["main_frame"]
}
}
]
This ruleset defines five basic blocking rules for common distracting websites. Each rule has a unique ID, a priority (used when multiple rules might match a request), an action type (block), and conditions that specify when the rule should apply.
We need to update the manifest.json to reference this ruleset:
"declarative_net_request": {
"rule_resources": [{
"id": "blocking_rules",
"enabled": true,
"path": "rules/blocking-rules.json"
}]
}
The ruleset approach has several advantages for our deep work extension. It is more performant than content scripts because the blocking happens at the network level before any page content is loaded. It is also more privacy-friendly because Chrome handles the blocking without needing to share page content with the extension. Finally, it works even when the service worker is not actively running, which improves reliability for longer focus sessions.
Building the Popup User Interface
The popup provides the primary user interface for the extension, allowing users to start and stop focus sessions, configure blocked sites, and view the current focus state. A well-designed popup should be intuitive and provide clear feedback about the extension’s current status.
<!-- popup/popup.html -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Focus Mode Pro</title>
<link rel="stylesheet" href="popup.css">
</head>
<body>
<div class="container">
<header>
<h1>Focus Mode</h1>
<div class="status-indicator" id="statusIndicator">
<span class="status-dot"></span>
<span class="status-text" id="statusText">Ready to Focus</span>
</div>
</header>
<main>
<div class="timer-section" id="timerSection">
<div class="timer-display" id="timerDisplay">25:00</div>
<div class="timer-controls">
<button class="btn btn-primary" id="startBtn">Start Focus</button>
<button class="btn btn-secondary hidden" id="stopBtn">Stop</button>
</div>
</div>
<div class="duration-section">
<label for="durationSelect">Focus Duration:</label>
<select id="durationSelect">
<option value="15">15 minutes</option>
<option value="25" selected>25 minutes</option>
<option value="30">30 minutes</option>
<option value="45">45 minutes</option>
<option value="60">1 hour</option>
<option value="90">1.5 hours</option>
<option value="120">2 hours</option>
</select>
</div>
<div class="blocked-sites-section">
<h2>Blocked Sites</h2>
<div class="site-input-group">
<input type="text" id="siteInput" placeholder="Enter website domain (e.g., twitter.com)">
<button class="btn btn-small" id="addSiteBtn">Add</button>
</div>
<ul class="blocked-sites-list" id="blockedSitesList">
<!-- Sites will be added dynamically -->
</ul>
</div>
<div class="stats-section hidden" id="statsSection">
<h2>Today's Progress</h2>
<div class="stat">
<span class="stat-label">Sessions Completed:</span>
<span class="stat-value" id="sessionsCompleted">0</span>
</div>
<div class="stat">
<span class="stat-label">Total Focus Time:</span>
<span class="stat-value" id="totalFocusTime">0 min</span>
</div>
</div>
</main>
</div>
<script src="popup.js"></script>
</body>
</html>
This HTML provides a clean, organized layout with sections for the timer display, duration selection, blocked sites management, and progress statistics. The interface uses CSS classes for styling and JavaScript for interactivity.
Styling the Popup Interface
The CSS styling transforms our HTML into a visually appealing interface that users will enjoy interacting with throughout their focus sessions. Good design is particularly important for productivity extensions because users should feel motivated to use the tool regularly.
/* popup/popup.css */
* {
margin: 0;
padding: 0;
box-sizing: border-box;
}
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
min-width: 320px;
color: #333;
}
.container {
padding: 20px;
}
header {
text-align: center;
margin-bottom: 24px;
color: white;
}
header h1 {
font-size: 24px;
font-weight: 600;
margin-bottom: 12px;
}
.status-indicator {
display: flex;
align-items: center;
justify-content: center;
gap: 8px;
}
.status-dot {
width: 10px;
height: 10px;
border-radius: 50%;
background-color: #ccc;
transition: background-color 0.3s ease;
}
.status-dot.active {
background-color: #4ade80;
animation: pulse 2s infinite;
}
@keyframes pulse {
0%, 100% {
opacity: 1;
}
50% {
opacity: 0.5;
}
}
.status-text {
font-size: 14px;
opacity: 0.9;
}
.timer-section {
background: white;
border-radius: 12px;
padding: 24px;
text-align: center;
margin-bottom: 16px;
box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
}
.timer-display {
font-size: 48px;
font-weight: 700;
color: #1a1a2e;
margin-bottom: 16px;
font-variant-numeric: tabular-nums;
}
.timer-controls {
display: flex;
gap: 12px;
justify-content: center;
}
.btn {
padding: 12px 24px;
border: none;
border-radius: 8px;
font-size: 16px;
font-weight: 600;
cursor: pointer;
transition: all 0.2s ease;
}
.btn-primary {
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
color: white;
}
.btn-primary:hover {
transform: translateY(-2px);
box-shadow: 0 4px 12px rgba(102, 126, 234, 0.4);
}
.btn-secondary {
background: #e5e7eb;
color: #374151;
}
.btn-secondary:hover {
background: #d1d5db;
}
.btn-small {
padding: 8px 16px;
font-size: 14px;
}
.hidden {
display: none !important;
}
.duration-section {
background: white;
border-radius: 12px;
padding: 16px;
margin-bottom: 16px;
box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
}
.duration-section label {
display: block;
font-size: 14px;
font-weight: 500;
margin-bottom: 8px;
color: #374151;
}
.duration-section select {
width: 100%;
padding: 10px;
border: 1px solid #d1d5db;
border-radius: 6px;
font-size: 14px;
background: white;
}
.blocked-sites-section {
background: white;
border-radius: 12px;
padding: 16px;
margin-bottom: 16px;
box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
}
.blocked-sites-section h2 {
font-size: 16px;
font-weight: 600;
margin-bottom: 12px;
color: #1a1a2e;
}
.site-input-group {
display: flex;
gap: 8px;
margin-bottom: 12px;
}
.site-input-group input {
flex: 1;
padding: 10px;
border: 1px solid #d1d5db;
border-radius: 6px;
font-size: 14px;
}
.blocked-sites-list {
list-style: none;
max-height: 150px;
overflow-y: auto;
}
.blocked-sites-list li {
display: flex;
justify-content: space-between;
align-items: center;
padding: 8px 0;
border-bottom: 1px solid #f3f4f6;
}
.blocked-sites-list li:last-child {
border-bottom: none;
}
.remove-site-btn {
background: none;
border: none;
color: #ef4444;
cursor: pointer;
font-size: 18px;
line-height: 1;
}
.stats-section {
background: white;
border-radius: 12px;
padding: 16px;
box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
}
.stats-section h2 {
font-size: 16px;
font-weight: 600;
margin-bottom: 12px;
color: #1a1a2e;
}
.stat {
display: flex;
justify-content: space-between;
padding: 8px 0;
}
.stat-label {
color: #6b7280;
font-size: 14px;
}
.stat-value {
font-weight: 600;
color: #1a1a2e;
}
This CSS creates a modern, gradient-themed interface that feels professional and motivating. The design includes visual feedback mechanisms like the pulsing status indicator that helps users understand the current focus state at a glance.
Implementing Popup JavaScript Logic
The popup JavaScript handles user interactions, communicates with the background service worker, and updates the interface in response to state changes. This script connects the user interface to the underlying focus session management logic.
// popup/popup.js
// DOM Elements
const startBtn = document.getElementById('startBtn');
const stopBtn = document.getElementById('stopBtn');
const timerDisplay = document.getElementById('timerDisplay');
const statusIndicator = document.getElementById('statusIndicator');
const statusText = document.getElementById('statusText');
const durationSelect = document.getElementById('durationSelect');
const siteInput = document.getElementById('siteInput');
const addSiteBtn = document.getElementById('addSiteBtn');
const blockedSitesList = document.getElementById('blockedSitesList');
const statsSection = document.getElementById('statsSection');
const sessionsCompleted = document.getElementById('sessionsCompleted');
const totalFocusTime = document.getElementById('totalFocusTime');
// State
let blockedSites = ['facebook.com', 'twitter.com', 'instagram.com', 'youtube.com', 'reddit.com'];
let focusState = {
isActive: false,
endTime: null,
focusDuration: 25
};
let timerInterval = null;
// Initialize
document.addEventListener('DOMContentLoaded', () => {
loadState();
renderBlockedSites();
updateUI();
});
// Load state from background
function loadState() {
chrome.runtime.sendMessage({ type: 'GET_STATE' }, (response) => {
if (response && response.state) {
focusState = response.state;
updateUI();
}
});
}
// Update UI based on current state
function updateUI() {
if (focusState.isActive) {
startBtn.classList.add('hidden');
stopBtn.classList.remove('hidden');
statusText.textContent = 'Focus Mode Active';
statusIndicator.querySelector('.status-dot').classList.add('active');
statsSection.classList.remove('hidden');
durationSelect.disabled = true;
startTimerDisplay();
} else {
startBtn.classList.remove('hidden');
stopBtn.classList.add('hidden');
statusText.textContent = 'Ready to Focus';
statusIndicator.querySelector('.status-dot').classList.remove('active');
durationSelect.disabled = false;
if (timerInterval) {
clearInterval(timerInterval);
timerInterval = null;
}
timerDisplay.textContent = formatTime(focusState.focusDuration * 60);
}
}
// Start timer display updates
function startTimerDisplay() {
if (timerInterval) {
clearInterval(timerInterval);
}
updateTimerDisplay();
timerInterval = setInterval(updateTimerDisplay, 1000);
}
// Update timer display
function updateTimerDisplay() {
if (!focusState.endTime) return;
const remaining = Math.max(0, focusState.endTime - Date.now());
if (remaining <= 0) {
// Session completed
clearInterval(timerInterval);
focusState.isActive = false;
loadState(); // Reload from background
return;
}
timerDisplay.textContent = formatTime(Math.ceil(remaining / 1000));
}
// Format seconds to MM:SS
function formatTime(seconds) {
const mins = Math.floor(seconds / 60);
const secs = seconds % 60;
return `${mins.toString().padStart(2, '0')}:${secs.toString().padStart(2, '0')}`;
}
// Start focus session
startBtn.addEventListener('click', () => {
const duration = parseInt(durationSelect.value);
chrome.runtime.sendMessage({
type: 'START_FOCUS',
duration: duration,
blockedSites: blockedSites
}, (response) => {
if (response && response.success) {
focusState = response.state;
updateUI();
}
});
});
// Stop focus session
stopBtn.addEventListener('click', () => {
chrome.runtime.sendMessage({ type: 'STOP_FOCUS' }, (response) => {
if (response && response.success) {
focusState = response.state;
updateUI();
}
});
});
// Add blocked site
addSiteBtn.addEventListener('click', addSite);
siteInput.addEventListener('keypress', (e) => {
if (e.key === 'Enter') {
addSite();
}
});
function addSite() {
const site = siteInput.value.trim().toLowerCase();
// Basic validation
if (!site) return;
if (!site.includes('.') && site.length > 2) {
// Likely a domain without TLD, add .com
site = site + '.com';
}
if (!blockedSites.includes(site)) {
blockedSites.push(site);
renderBlockedSites();
saveBlockedSites();
}
siteInput.value = '';
}
// Remove blocked site
function removeSite(site) {
blockedSites = blockedSites.filter(s => s !== site);
renderBlockedSites();
saveBlockedSites();
}
// Render blocked sites list
function renderBlockedSites() {
blockedSitesList.innerHTML = '';
blockedSites.forEach(site => {
const li = document.createElement('li');
li.innerHTML = `
<span>${site}</span>
<button class="remove-site-btn" data-site="${site}">×</button>
`;
blockedSitesList.appendChild(li);
});
// Add event listeners to remove buttons
document.querySelectorAll('.remove-site-btn').forEach(btn => {
btn.addEventListener('click', () => {
removeSite(btn.dataset.site);
});
});
}
// Save blocked sites to storage
function saveBlockedSites() {
chrome.runtime.sendMessage({
type: 'UPDATE_BLOCKED_SITES',
blockedSites: blockedSites
});
}
This JavaScript implements the client-side logic for the popup interface. It handles starting and stopping focus sessions, managing the blocked sites list, updating the timer display in real-time, and communicating with the background service worker to maintain consistent state across the extension.
Advanced Features and Enhancements
Now that we have a functional focus mode extension, let us explore several advanced features that can make your extension stand out in the Chrome Web Store and provide additional value to users.
One powerful enhancement is the ability to create scheduled focus sessions that automatically start at specific times. This feature would allow users to set up recurring focus periods, such as “work hours” from 9 AM to 5 PM, during which distracting sites are automatically blocked. Implementing this requires using Chrome’s alarms API to schedule periodic checks and maintain the blocking state throughout the day.
Another valuable addition is integration with task management systems. By allowing users to link specific focus sessions to tasks or projects, the extension can provide productivity analytics that show correlations between focus time and task completion. This data can be incredibly motivating for users who want to understand and optimize their work patterns.
A more sophisticated feature would be progressive blocking, where the extension gradually increases restrictions based on the user’s behavior. For example, if a user tries to access a blocked site repeatedly within a short period, the extension might provide additional encouragement or resources for staying focused, such as displaying a motivational quote or suggesting a brief breathing exercise.
Browser sync is another important feature for users who work across multiple devices. By leveraging Chrome’s sync storage API, the extension can maintain consistent settings and statistics across all the user’s devices, ensuring a seamless experience whether they are working on a laptop at home or a desktop at the office.
Testing and Deployment
Before publishing your focus mode extension to the Chrome Web Store, thorough testing is essential to ensure a smooth user experience. Chrome provides several tools for testing extensions during development, including the Extensions Management page (chrome://extensions) which allows you to load unpacked extensions for testing and debugging.
Pay particular attention to testing edge cases such as what happens when a focus session is interrupted by a browser restart, how the extension handles very long focus sessions (several hours), and what happens when users try to access blocked sites through various methods including direct URL entry, bookmarks, and search engine results.
When you are ready to publish, create a developer account on the Chrome Web Store developer dashboard, prepare your store listing with compelling screenshots and descriptions, and submit your extension for review. The review process typically takes a few days, after which your extension will be available to millions of Chrome users looking for ways to improve their productivity.
Conclusion
Building a focus mode extension represents an excellent opportunity to create a genuinely useful tool that addresses a real problem faced by millions of people in the modern digital workplace. The combination of website blocking, customizable focus timers, and progress tracking provides a comprehensive solution for achieving deep work states and maximizing productivity.
Throughout this guide, we have covered the essential components of a professional-grade Chrome extension, including Manifest V3 configuration, background service worker implementation, declarative net request rules for content blocking, and polished user interface design. These skills form a solid foundation that you can build upon to add more advanced features and create an increasingly sophisticated productivity tool.
The key to success with any productivity extension lies in balancing powerful features with simplicity and ease of use. Users should be able to start a focus session with a single click, but also have access to sophisticated customization options when they need them. By following the patterns and practices outlined in this guide, you will be well-equipped to create an extension that helps users achieve their goals and maintain focus in an increasingly distracting digital world.