Building Chrome Extensions with JavaScript: A Complete Guide

// File: background.js
// Runs as the extension's event-driven service worker.

console.log("Page Insights service worker started.");

chrome.runtime.onInstalled.addListener(async (details) => {
  console.log("Extension installation event:", details.reason);

  // Initialize extension settings only when they do not exist.
  const settings = await chrome.storage.local.get("settings");

  if (!settings.settings) {
    await chrome.storage.local.set({
      settings: {
        saveHistory: true,
        version: "1.0.0"
      }
    });

    console.log("Default extension settings initialized.");
  }
});

// File: popup.js
// Handles the popup UI and requests webpage analysis.

document.addEventListener("DOMContentLoaded", () => {
  const analyzeButton = document.getElementById("analyzeButton");
  const statusElement = document.getElementById("status");
  const resultsElement = document.getElementById("results");
  const saveButton = document.getElementById("saveButton");

  let latestAnalysis = null;

  console.log("Popup initialized. Waiting for user interaction.");

  // Display a message without inserting webpage-provided HTML.
  function setStatus(message) {
    statusElement.textContent = message;
  }

  // Render the analysis using safe DOM text operations.
  function renderResults(data) {
    resultsElement.replaceChildren();

    const fields = [
      ["Page title", data.title],
      ["Word count", String(data.wordCount)],
      ["Character count", String(data.characterCount)],
      ["Reading time", `${data.readingTimeMinutes} minute(s)`],
      ["Page URL", data.url]
    ];

    for (const [label, value] of fields) {
      const row = document.createElement("p");
      const strong = document.createElement("strong");

      strong.textContent = `${label}: `;
      row.append(strong, document.createTextNode(value));
      resultsElement.appendChild(row);
    }
  }

  // Analyze the currently active tab after an explicit user click.
  analyzeButton.addEventListener("click", async () => {
    analyzeButton.disabled = true;
    saveButton.disabled = true;
    setStatus("Analyzing the current page...");
    resultsElement.replaceChildren();

    try {
      console.log("Step 1: Finding the active browser tab.");

      const [tab] = await chrome.tabs.query({
        active: true,
        currentWindow: true
      });

      if (!tab || !tab.id || !tab.url) {
        throw new Error("No active browser tab was found.");
      }

      // Chrome restricts injection into internal browser pages.
      const pageUrl = new URL(tab.url);

      if (!["http:", "https:"].includes(pageUrl.protocol)) {
        throw new Error("Open a regular HTTP or HTTPS webpage first.");
      }

      console.log("Step 2: Extracting webpage information.");

      const injectionResults = await chrome.scripting.executeScript({
        target: { tabId: tab.id },
        func: () => {
          // This function executes in the target webpage.
          const title = document.title || "Untitled page";
          const url = window.location.href;
          const text = document.body?.innerText || "";
          const words = text.trim().match(/\S+/g) || [];

          return {
            title,
            url,
            wordCount: words.length,
            characterCount: text.length,
            // Approximate reading speed: 200 words per minute.
            readingTimeMinutes: Math.max(
              1,
              Math.ceil(words.length / 200)
            ),
            analyzedAt: new Date().toISOString()
          };
        }
      });

      const result = injectionResults[0]?.result;

      if (!result) {
        throw new Error("The page did not return analysis results.");
      }

      console.log("Step 3: Analysis completed successfully.");
      console.log("Extracted analysis:", result);

      latestAnalysis = result;
      renderResults(result);
      saveButton.disabled = false;
      setStatus("Analysis completed successfully.");
    } catch (error) {
      // Permission restrictions and inaccessible tabs are handled here.
      console.error("Page analysis failed:", error);
      setStatus(error.message || "Unable to analyze this page.");
    } finally {
      analyzeButton.disabled = false;
    }
  });

  // Save the most recent analysis in extension-local storage.
  saveButton.addEventListener("click", async () => {
    if (!latestAnalysis) {
      setStatus("Analyze a page before saving its results.");
      return;
    }

    try {
      console.log("Step 4: Saving analysis to local extension storage.");

      const stored = await chrome.storage.local.get("history");
      const history = Array.isArray(stored.history)
        ? stored.history
        : [];

      // Keep the most recent 20 results to limit storage growth.
      const updatedHistory = [latestAnalysis, ...history].slice(0, 20);

      await chrome.storage.local.set({ history: updatedHistory });

      console.log("Step 5: Analysis saved.", updatedHistory.length);
      setStatus("Analysis saved locally.");
    } catch (error) {
      console.error("Failed to save analysis:", error);
      setStatus("Could not save the analysis.");
    }
  });
});

// File: manifest.json
// Keep this JSON in a separate file, not inside popup.js.
// {
//   "manifest_version": 3,
//   "name": "Page Insights",
//   "version": "1.0.0",
//   "description": "Analyze webpage text and estimate reading time.",
//   "permissions": ["activeTab", "scripting", "storage"],
//   "background": { "service_worker": "background.js" },
//   "action": {
//     "default_popup": "popup.html",
//     "default_title": "Page Insights"
//   }
// }

// File: popup.html
// Create a separate popup.html file with the following markup.
// <!DOCTYPE html>
// <html lang="en">
// <head>
//   <meta charset="UTF-8">
//   <meta name="viewport" content="width=device-width, initial-scale=1.0">
//   <title>Page Insights</title>
// </head>
// <body>
//   <h1>Page Insights</h1>
//   <button id="analyzeButton">Analyze Page</button>
//   <div id="results"></div>
//   <button id="saveButton" disabled>Save Analysis</button>
//   <p id="status" role="status">Ready to analyze a page.</p>
//   <script src="popup.js"></script>
// </body>
// </html>

// Testing checklist:
// 1. Save each file separately in the project directory.
// 2. Load the directory using chrome://extensions.
// 3. Open a normal webpage and click the extension icon.
// 4. Select Analyze Page and inspect the popup results.
// 5. Select Save Analysis and inspect chrome.storage.local.
// 6. Check the extension's service worker console for installation logs.