Build a Reading List Chrome Extension: Complete Step-by-Step Guide

20 min read

Build a Reading List Chrome Extension: Complete Step-by-Step Guide

· 19 min read · Chrome Extensions, Tutorial

Build a Reading List Chrome Extension: Complete Step-by-Step Guide

Creating your own reading list Chrome extension is one of the most rewarding projects you can undertake as a developer. Whether you want to save articles for later reading, build a bookmark reader, or create a sophisticated save for later extension with cloud sync, this guide will walk you through the entire process. By the end of this tutorial, you will have a fully functional reading list extension that you can use and customize to your heart’s content.

The demand for reading list extensions has skyrocketed in recent years as internet users consume more content than ever before. With the average person browsing hundreds of web pages daily, the need to save and organize content for later consumption has become essential. Building your own reading list extension not only solves this problem but also provides valuable experience with Chrome extension development, Manifest V3 APIs, and modern web storage solutions.

Why Build a Reading List Extension

Before diving into the code, let us explore why building a reading list extension is an excellent project choice. First and foremost, it addresses a real problem that millions of Chrome users face daily. Whether you are a researcher collecting articles, a student gathering study materials, or simply someone who wants to save interesting content for later, a custom reading list extension provides exactly what you need.

From a technical perspective, a reading list extension encompasses many fundamental concepts in Chrome extension development. You will work with content scripts to capture page information, background scripts for managing extension state, the Chrome Storage API for persisting data, and popup interfaces for user interaction. This makes it an ideal starter project for anyone new to extension development while still offering plenty of room for advanced features as your skills grow.

The reading list extension category is also highly relevant in today’s content-heavy internet landscape. Users constantly search for solutions to save articles for later, organize their bookmarks, and access saved content across devices. By mastering this type of extension, you gain skills that apply directly to building other productivity tools like note-taking apps, bookmark managers, and content aggregators.

Project Architecture and Requirements

Every successful Chrome extension begins with a solid architectural foundation. For our reading list extension, we need to carefully plan the components that will work together seamlessly. Let us break down the essential elements and understand how they interact.

Core Components

Our reading list extension consists of several interconnected parts that each handle specific responsibilities. The manifest file serves as the configuration hub, defining permissions, defining the extension’s capabilities, and specifying which files Chrome should load. The popup interface provides the primary user interaction point, allowing users to view their saved articles and manage their reading list. Content scripts run on web pages to capture page information when the user decides to save it, while the background script handles any long-running tasks or message passing between components.

The data layer utilizes Chrome’s storage API to persist the reading list locally. This approach ensures that users can access their saved articles even without an internet connection, though we will also discuss how to implement cloud sync for users who want to access their reading list across multiple devices. The storage structure needs to accommodate article titles, URLs, excerpts, featured images, timestamps, and any user-added notes or tags.

Manifest V3 Requirements

Since Google deprecated Manifest V2 in 2023, all new extensions must use Manifest V3. This version introduces several important changes that affect how we build extensions. The most significant change involves background scripts, which now use service workers instead of persistent background pages. We also have new limitations on remote code execution and modifications to how content scripts operate.

For our reading list extension, we need to declare specific permissions in the manifest. The activeTab permission allows our content script to access the current page when the user explicitly invokes our extension. The storage permission enables us to persist the reading list data. We will also need to specify host permissions for the websites where we want our extension to capture page information effectively.

Setting Up the Project Structure

With the architecture defined, let us create the physical files that comprise our extension. A well-organized project structure makes development easier and your extension more maintainable over time. We will create a directory structure that separates concerns while keeping related files together.

Directory Structure

The recommended structure for our reading list extension keeps all extension files organized and easy to navigate. At the root level, we have our manifest.json file, which Chrome reads to understand our extension’s configuration. The popup directory contains all files related to the popup interface, including HTML, CSS, and JavaScript. The content directory houses our content scripts that run on web pages, while the background directory contains our service worker code. Finally, the assets directory stores icons and other static resources.

This organization separates the different parts of our extension logically. When you need to work on the popup interface, you know exactly where to look. When debugging content scripts, the relevant files are in their own directory. This structure also scales well as you add more features to your extension.

Creating the Manifest File

The manifest.json file is the heart of any Chrome extension. Let us create a comprehensive manifest that supports all the features we need for our reading list extension. We will use Manifest V3 syntax and include all necessary permissions and declarations.

{
  "manifest_version": 3,
  "name": "Reading List Manager",
  "version": "1.0.0",
  "description": "Save and organize articles for later reading",
  "permissions": [
    "activeTab",
    "storage"
  ],
  "host_permissions": [
    "<all_urls>"
  ],
  "action": {
    "default_popup": "popup/popup.html",
    "default_icon": {
      "16": "assets/icon16.png",
      "48": "assets/icon48.png",
      "128": "assets/icon128.png"
    }
  },
  "background": {
    "service_worker": "background/background.js"
  },
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["content/content.js"],
      "run_at": "document_idle"
    }
  ],
  "icons": {
    "16": "assets/icon16.png",
    "48": "assets/icon48.png",
    "128": "assets/icon128.png"
  }
}

This manifest defines everything Chrome needs to load our extension correctly. The permissions array includes activeTab for accessing page content and storage for persisting our reading list. Host permissions allow our extension to work on any website. The action section defines our popup, and the background and content_scripts sections register our JavaScript files.

The popup serves as the main interface through which users interact with our reading list extension. When users click the extension icon, they should see their saved articles, be able to add new items, and manage their existing collection. Let us build a clean, functional popup that provides all these capabilities.

HTML Structure

Our popup HTML should be simple but functional. We need a header with the extension title, an area to display the reading list items, and a way to add new items. The structure should be intuitive and work well on different screen sizes, since Chrome popups have limited width.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Reading List</title>
  <link rel="stylesheet" href="popup/popup.css">
</head>
<body>
  <div class="container">
    <header>
      <h1>Reading List</h1>
      <button id="addCurrentTab" class="primary-btn">Save Current Page</button>
    </header>
    <div id="readingList" class="reading-list"></div>
    <div id="emptyState" class="empty-state hidden">
      <p>No articles saved yet.</p>
      <p>Click "Save Current Page" to add your first article.</p>
    </div>
  </div>
  <script src="popup/popup.js"></script>
</body>
</html>

Styling the Popup

The CSS should provide a clean, modern appearance that matches Chrome’s design language. We want the popup to feel native and responsive. Key considerations include adequate spacing, clear typography, and visual feedback for user actions.

* {
  box-sizing: border-box;
  margin: 0;
  padding: 0;
}

body {
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;
  width: 350px;
  min-height: 400px;
  background: #fafafa;
}

.container {
  padding: 16px;
}

header {
  display: flex;
  flex-direction: column;
  gap: 12px;
  margin-bottom: 16px;
  padding-bottom: 16px;
  border-bottom: 1px solid #e0e0e0;
}

h1 {
  font-size: 18px;
  color: #333;
}

.primary-btn {
  background: #4285f4;
  color: white;
  border: none;
  padding: 10px 16px;
  border-radius: 4px;
  cursor: pointer;
  font-size: 14px;
  font-weight: 500;
  transition: background 0.2s;
}

.primary-btn:hover {
  background: #3367d6;
}

.reading-list {
  display: flex;
  flex-direction: column;
  gap: 12px;
}

.article-item {
  background: white;
  border: 1px solid #e0e0e0;
  border-radius: 8px;
  padding: 12px;
  transition: box-shadow 0.2s;
}

.article-item:hover {
  box-shadow: 0 2px 8px rgba(0,0,0,0.1);
}

.article-title {
  font-size: 14px;
  font-weight: 600;
  color: #202124;
  margin-bottom: 4px;
  display: -webkit-box;
  -webkit-line-clamp: 2;
  -webkit-box-orient: vertical;
  overflow: hidden;
}

.article-url {
  font-size: 12px;
  color: #5f6368;
  margin-bottom: 8px;
  white-space: nowrap;
  overflow: hidden;
  text-overflow: ellipsis;
}

.article-actions {
  display: flex;
  gap: 8px;
}

.delete-btn {
  background: #fce8e6;
  color: #c5221f;
  border: none;
  padding: 6px 12px;
  border-radius: 4px;
  cursor: pointer;
  font-size: 12px;
}

.delete-btn:hover {
  background: #fad2cf;
}

.empty-state {
  text-align: center;
  padding: 40px 20px;
  color: #5f6368;
}

.hidden {
  display: none;
}

The popup JavaScript handles displaying the reading list, adding new articles, and deleting existing ones. It communicates with Chrome’s storage API to persist data and with the background script when needed.

document.addEventListener('DOMContentLoaded', async () => {
  const readingListElement = document.getElementById('readingList');
  const emptyStateElement = document.getElementById('emptyState');
  const addButton = document.getElementById('addCurrentTab');

  // Load and display the reading list
  async function loadReadingList() {
    const result = await chrome.storage.local.get('readingList');
    const articles = result.readingList || [];
    
    if (articles.length === 0) {
      readingListElement.classList.add('hidden');
      emptyStateElement.classList.remove('hidden');
      return;
    }
    
    readingListElement.classList.remove('hidden');
    emptyStateElement.classList.add('hidden');
    
    renderArticles(articles);
  }

  function renderArticles(articles) {
    readingListElement.innerHTML = articles.map((article, index) => `
      <div class="article-item" data-index="${index}">
        <div class="article-title">${escapeHtml(article.title)}</div>
        <div class="article-url">${escapeHtml(article.url)}</div>
        <div class="article-actions">
          <a href="${escapeHtml(article.url)}" target="_blank" class="primary-btn">Open</a>
          <button class="delete-btn" onclick="deleteArticle(${index})">Delete</button>
        </div>
      </div>
    `).join('');
  }

  window.deleteArticle = async (index) => {
    const result = await chrome.storage.local.get('readingList');
    const articles = result.readingList || [];
    articles.splice(index, 1);
    await chrome.storage.local.set({ readingList: articles });
    loadReadingList();
  };

  addButton.addEventListener('click', async () => {
    const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
    if (!tab) return;

    const article = {
      title: tab.title || 'Untitled',
      url: tab.url,
      savedAt: new Date().toISOString()
    };

    const result = await chrome.storage.local.get('readingList');
    const articles = result.readingList || [];
    articles.unshift(article);
    await chrome.storage.local.set({ readingList: articles });
    loadReadingList();
  });

  function escapeHtml(text) {
    const div = document.createElement('div');
    div.textContent = text;
    return div.innerHTML;
  }

  loadReadingList();
});

Content Script Implementation

Content scripts run in the context of web pages and can extract information from them. For our reading list extension, the content script can capture additional metadata when saving articles, such as the page description, featured image, or selected text. Let us create a content script that enhances our article data.

// content/content.js
// This content script can extract additional metadata from pages

function extractPageMetadata() {
  const metadata = {
    title: document.title,
    description: getMetaContent('description'),
    image: getMetaContent('og:image') || getMetaContent('twitter:image'),
    author: getMetaContent('author') || getMetaContent('og:article:author'),
    publishedTime: getMetaContent('article:published_time'),
    siteName: getMetaContent('og:site_name')
  };
  return metadata;
}

function getMetaContent(name) {
  const meta = document.querySelector(`meta[name="${name}"], meta[property="${name}"]`);
  return meta ? meta.content : null;
}

// Listen for messages from the popup or background script
chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
  if (request.action === 'getPageMetadata') {
    const metadata = extractPageMetadata();
    sendResponse(metadata);
  }
  return true;
});

Background Service Worker

In Manifest V3, background scripts become service workers that handle events rather than running continuously. Our background script can handle various tasks like managing extension state, responding to browser events, and coordinating between different parts of our extension.

// background/background.js

// Handle installation
chrome.runtime.onInstalled.addListener(() => {
  console.log('Reading List Extension installed');
  // Initialize storage if needed
  chrome.storage.local.get('readingList', (result) => {
    if (!result.readingList) {
      chrome.storage.local.set({ readingList: [] });
    }
  });
});

// Handle messages from popup or content scripts
chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
  if (request.action === 'saveArticle') {
    saveArticle(request.article).then(sendResponse);
    return true;
  }
});

async function saveArticle(article) {
  const result = await chrome.storage.local.get('readingList');
  const articles = result.readingList || [];
  articles.unshift({
    ...article,
    savedAt: new Date().toISOString()
  });
  await chrome.storage.local.set({ readingList: articles });
  return { success: true };
}

Enhancing the User Experience

Now that we have the core functionality working, let us explore ways to enhance our reading list extension. These improvements will make our extension more useful and professional.

Adding Search and Filter

A reading list can quickly grow large, making it difficult to find specific articles. Adding search functionality allows users to quickly locate saved articles by title or URL. We can implement this in our popup JavaScript by filtering the displayed articles based on user input.

Implementing Tags and Categories

Allowing users to organize their saved articles with tags adds significant value. Users could tag articles as “Research,” “Tutorial,” or “To Read Later,” and filter their list accordingly. This requires updating our storage structure to include a tags array for each article and modifying the popup interface to support tag management.

Adding Read/Unread Status

Tracking which articles users have read helps them prioritize their reading list. We can add a simple read status to each article item and allow users to toggle this status. Unread articles could be highlighted to help users focus on content they have not yet explored.

Cloud Synchronization

While local storage works well for individual users, many people want to access their reading list across multiple devices. Implementing cloud sync would require a backend service to store and retrieve user data. You could use Firebase, Supabase, or a custom backend with user authentication. This advanced feature significantly increases complexity but provides substantial value for users who work across multiple devices.

Testing Your Extension

Before publishing your extension, thorough testing ensures everything works correctly. Chrome provides excellent developer tools for testing extensions.

Loading the Extension

To test your extension in development, navigate to chrome://extensions/ in Chrome, enable Developer mode using the toggle in the top right corner, and click “Load unpacked.” Select your extension’s directory, and Chrome will load it. Any changes you make to the code require you to click the refresh icon on your extension card or reload the extension.

Debugging Tips

Chrome provides separate devtools for extensions. Right-click anywhere in your popup and choose “Inspect” to open the popup’s developer tools. For background scripts, click “Service worker” in your extension’s card to access its console. Content scripts can be debugged like regular web page scripts when you visit a page where the content script runs.

Publishing Your Extension

Once you have tested your extension and are satisfied with its functionality, you can publish it to the Chrome Web Store. This process involves creating a developer account, preparing your extension for publication, and submitting it for review.

Developer Account Setup

Visit the Chrome Web Store developer dashboard and create an account. There is a one-time registration fee for new developers. You will need to provide payment information and verify your identity.

Preparing for Publication

Before submitting, ensure your extension meets all Chrome Web Store policies. Create compelling store listing assets including a logo, screenshots, and a detailed description. Use the keywords you researched to optimize your listing for searchability.

Submitting Your Extension

Package your extension using the “Pack extension” button in chrome://extensions/ or create a ZIP file of your extension directory. Upload this ZIP to the Chrome Web Store developer dashboard, fill in your store listing details, and submit for review. The review process typically takes a few days.

Conclusion

Building a reading list Chrome extension is an excellent project that teaches valuable skills while creating a genuinely useful tool. You have learned how to set up a Manifest V3 extension, create a popup interface, implement content scripts, work with Chrome’s storage API, and structure your code for maintainability.

The foundation we built here provides everything needed to create a fully functional save for later extension. From here, you can add advanced features like cloud sync, tags, search functionality, or integration with third-party services. The Chrome extension ecosystem offers endless possibilities for developers willing to explore.

Remember that the best extensions solve real problems for real users. As you continue development, gather feedback from users and iterate on your design. With persistence and creativity, your reading list extension could become an essential tool for thousands of Chrome users seeking to organize their online reading.

No previous article
No next article