Build a Chrome Extension with GPT-5 in 45 Minutes

Create a working Chrome extension that uses GPT-5 API for text enhancement. Includes manifest v3, popup UI, and API integration.
·
9 min read
·
Mark
·
Web Development

Problem: You Want to Add AI to Your Browser Workflow

You need a custom Chrome extension that enhances text using GPT-5, but Chrome's Manifest v3 requirements and API security make it confusing to get started.

You'll learn:

  • How to structure a Manifest v3 extension with GPT-5
  • Secure API key handling in browser extensions
  • Building a functional popup with text enhancement
  • Publishing to Chrome Web Store basics

Time: 45 min | Level: Intermediate

Why Extensions Are Different Now

Chrome Manifest v3 (required since 2024) removed background pages and changed how extensions handle external APIs. You can't just fetch() from content scripts anymore.

Common symptoms:

  • CORS errors when calling GPT-5 API
  • API keys exposed in content scripts
  • Service workers timing out on long requests
  • Popup closes before API response returns

What We're Building

A text enhancement tool that:

  1. Highlights text on any webpage
  2. Right-click to send to GPT-5
  3. Shows improved version in popup
  4. Copies result to clipboard

Tech stack:

  • Manifest v3
  • Service Worker (background script)
  • Content Script (page interaction)
  • Popup HTML/CSS/JS
  • OpenAI GPT-5 API

Prerequisites

# Check Node.js version (needs 20+)
node --version  # Should show v20.x or higher

# Get OpenAI API key
# Visit https://platform.openai.com/api-keys

Cost: GPT-5 API costs ~$0.10 per 1K requests (as of Feb 2026). Set billing limits.

Solution

Step 1: Create Extension Structure

# Create project
mkdir text-enhancer-ext
cd text-enhancer-ext

# Create folder structure
mkdir -p src/{popup,content,background,styles}
touch manifest.json src/popup/{popup.html,popup.js} src/content/content.js src/background/service-worker.js

Expected: Clean folder structure separating concerns.

Step 2: Configure Manifest v3

{
  "manifest_version": 3,
  "name": "GPT-5 Text Enhancer",
  "version": "1.0.0",
  "description": "Enhance selected text with GPT-5",
  
  "permissions": [
    "activeTab",
    "contextMenus",
    "storage",
    "scripting"
  ],
  
  "host_permissions": [
    "https://api.openai.com/*"
  ],
  
  "background": {
    "service_worker": "src/background/service-worker.js"
  },
  
  "content_scripts": [{
    "matches": ["<all_urls>"],
    "js": ["src/content/content.js"]
  }],
  
  "action": {
    "default_popup": "src/popup/popup.html",
    "default_icon": {
      "16": "icons/icon16.png",
      "48": "icons/icon48.png",
      "128": "icons/icon128.png"
    }
  },
  
  "icons": {
    "16": "icons/icon16.png",
    "48": "icons/icon48.png",
    "128": "icons/icon128.png"
  }
}

Why this works: host_permissions allows API calls from service worker. activeTab lets us read selected text without broad permissions.

Step 3: Build Service Worker (Background Logic)

// src/background/service-worker.js

// Create context menu on install
chrome.runtime.onInstalled.addListener(() => {
  chrome.contextMenus.create({
    id: 'enhanceText',
    title: 'Enhance with GPT-5',
    contexts: ['selection']
  });
});

// Handle context menu click
chrome.contextMenus.onClicked.addListener(async (info, tab) => {
  if (info.menuItemId === 'enhanceText') {
    const selectedText = info.selectionText;
    
    // Store selected text temporarily
    await chrome.storage.local.set({ 
      selectedText,
      processing: true 
    });
    
    // Call GPT-5 API
    try {
      const enhanced = await enhanceWithGPT5(selectedText);
      await chrome.storage.local.set({ 
        enhancedText: enhanced,
        processing: false 
      });
      
      // Open popup to show result
      chrome.action.openPopup();
    } catch (error) {
      console.error('Enhancement failed:', error);
      await chrome.storage.local.set({ 
        error: error.message,
        processing: false 
      });
    }
  }
});

// GPT-5 API call
async function enhanceWithGPT5(text) {
  // Get API key from storage (user sets this in popup)
  const { apiKey } = await chrome.storage.local.get('apiKey');
  
  if (!apiKey) {
    throw new Error('API key not set. Click extension icon to configure.');
  }
  
  const response = await fetch('https://api.openai.com/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${apiKey}`
    },
    body: JSON.stringify({
      model: 'gpt-5-turbo',  // Use latest GPT-5 model
      messages: [{
        role: 'system',
        content: 'You are a professional editor. Improve the following text for clarity, grammar, and impact. Keep the same meaning and tone. Return only the improved text.'
      }, {
        role: 'user',
        content: text
      }],
      temperature: 0.7,
      max_tokens: 500
    })
  });
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error?.message || 'API request failed');
  }
  
  const data = await response.json();
  return data.choices[0].message.content;
}

// Keep service worker alive during long API calls
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === 'keepAlive') {
    sendResponse({ status: 'alive' });
  }
  return true;  // Required for async response
});

Why service worker: Only service workers can make external API calls in Manifest v3. Content scripts are blocked by CORS.

Security note: API key is stored in chrome.storage.local, which is isolated per-extension. Never hardcode keys.

Step 4: Create Popup Interface

<!-- src/popup/popup.html -->
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <style>
    body {
      width: 400px;
      min-height: 300px;
      padding: 16px;
      font-family: system-ui, -apple-system, sans-serif;
      margin: 0;
    }
    
    .setup {
      display: none;
    }
    
    .setup.active {
      display: block;
    }
    
    input {
      width: 100%;
      padding: 8px;
      margin: 8px 0;
      border: 1px solid #ddd;
      border-radius: 4px;
      font-size: 14px;
    }
    
    button {
      background: #1a73e8;
      color: white;
      border: none;
      padding: 10px 16px;
      border-radius: 4px;
      cursor: pointer;
      font-size: 14px;
      width: 100%;
      margin-top: 8px;
    }
    
    button:hover {
      background: #1557b0;
    }
    
    .result {
      display: none;
    }
    
    .result.active {
      display: block;
    }
    
    .text-box {
      background: #f8f9fa;
      padding: 12px;
      border-radius: 4px;
      margin: 12px 0;
      max-height: 200px;
      overflow-y: auto;
      font-size: 14px;
      line-height: 1.5;
    }
    
    .label {
      font-size: 12px;
      color: #5f6368;
      font-weight: 500;
      margin-bottom: 4px;
    }
    
    .processing {
      text-align: center;
      padding: 40px 0;
      color: #5f6368;
    }
    
    .error {
      color: #d93025;
      background: #fce8e6;
      padding: 12px;
      border-radius: 4px;
      font-size: 13px;
    }
    
    .success {
      color: #137333;
      background: #e6f4ea;
      padding: 8px;
      border-radius: 4px;
      font-size: 12px;
      margin-top: 8px;
    }
  </style>
</head>
<body>
  <!-- API Key Setup Screen -->
  <div id="setupScreen" class="setup">
    <h2>Setup Required</h2>
    <p>Enter your OpenAI API key to use GPT-5 text enhancement.</p>
    
    <div class="label">OpenAI API Key</div>
    <input 
      type="password" 
      id="apiKeyInput" 
      placeholder="sk-proj-..."
      autocomplete="off"
    >
    
    <button id="saveKeyBtn">Save Key</button>
    
    <p style="font-size: 12px; color: #5f6368; margin-top: 16px;">
      Get your key at 
      <a href="https://platform.openai.com/api-keys" target="_blank">
        platform.openai.com
      </a>
    </p>
  </div>
  
  <!-- Processing State -->
  <div id="processingScreen" style="display: none;">
    <div class="processing">
      <div>âš™ïž Enhancing text with GPT-5...</div>
    </div>
  </div>
  
  <!-- Results Screen -->
  <div id="resultScreen" class="result">
    <h2>Text Enhancement</h2>
    
    <div class="label">Original</div>
    <div id="originalText" class="text-box"></div>
    
    <div class="label">Enhanced by GPT-5</div>
    <div id="enhancedText" class="text-box"></div>
    
    <button id="copyBtn">📋 Copy Enhanced Text</button>
    <div id="copySuccess" class="success" style="display: none;">
      Copied to clipboard!
    </div>
    
    <div id="errorMsg" class="error" style="display: none;"></div>
  </div>
  
  <script src="popup.js"></script>
</body>
</html>

Step 5: Add Popup Logic

// src/popup/popup.js

document.addEventListener('DOMContentLoaded', async () => {
  const setupScreen = document.getElementById('setupScreen');
  const processingScreen = document.getElementById('processingScreen');
  const resultScreen = document.getElementById('resultScreen');
  
  // Check if API key exists
  const { apiKey } = await chrome.storage.local.get('apiKey');
  
  if (!apiKey) {
    // Show setup screen
    setupScreen.classList.add('active');
    
    document.getElementById('saveKeyBtn').addEventListener('click', async () => {
      const key = document.getElementById('apiKeyInput').value.trim();
      
      if (!key.startsWith('sk-')) {
        alert('Invalid API key format. Should start with sk-');
        return;
      }
      
      await chrome.storage.local.set({ apiKey: key });
      alert('API key saved! Right-click selected text to enhance it.');
      window.close();
    });
    
    return;
  }
  
  // Check if we have results to display
  const { processing, selectedText, enhancedText, error } = 
    await chrome.storage.local.get(['processing', 'selectedText', 'enhancedText', 'error']);
  
  if (processing) {
    processingScreen.style.display = 'block';
    return;
  }
  
  if (error) {
    resultScreen.classList.add('active');
    document.getElementById('errorMsg').textContent = error;
    document.getElementById('errorMsg').style.display = 'block';
    
    // Clear error after showing
    await chrome.storage.local.remove('error');
    return;
  }
  
  if (selectedText && enhancedText) {
    // Show results
    resultScreen.classList.add('active');
    document.getElementById('originalText').textContent = selectedText;
    document.getElementById('enhancedText').textContent = enhancedText;
    
    // Copy button
    document.getElementById('copyBtn').addEventListener('click', async () => {
      await navigator.clipboard.writeText(enhancedText);
      
      const successMsg = document.getElementById('copySuccess');
      successMsg.style.display = 'block';
      
      setTimeout(() => {
        successMsg.style.display = 'none';
      }, 2000);
    });
    
    // Clear results after displaying
    await chrome.storage.local.remove(['selectedText', 'enhancedText']);
  } else {
    // No results yet - show instructions
    resultScreen.innerHTML = `
      <h2>Ready to Use</h2>
      <p>To enhance text:</p>
      <ol style="padding-left: 20px; line-height: 1.8;">
        <li>Select text on any webpage</li>
        <li>Right-click the selection</li>
        <li>Choose "Enhance with GPT-5"</li>
      </ol>
      <button id="settingsBtn" style="background: #5f6368; margin-top: 16px;">
        🔑 Change API Key
      </button>
    `;
    resultScreen.classList.add('active');
    
    document.getElementById('settingsBtn')?.addEventListener('click', async () => {
      await chrome.storage.local.remove('apiKey');
      window.location.reload();
    });
  }
});

Why popup approach: Popup persists until user closes it, unlike notifications. Can show before/after comparison.

Step 6: Add Content Script (Optional Enhancement)

// src/content/content.js

// Add visual feedback when text is selected
let selectionTimeout;

document.addEventListener('mouseup', () => {
  clearTimeout(selectionTimeout);
  
  selectionTimeout = setTimeout(() => {
    const selection = window.getSelection();
    const text = selection.toString().trim();
    
    if (text.length > 10) {
      // Show subtle indicator that text can be enhanced
      console.log('💡 Right-click to enhance this text with GPT-5');
    }
  }, 100);
});

// Listen for messages from background script
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === 'textEnhanced') {
    // Could show notification or highlight
    console.log('✓ Text enhanced successfully');
  }
});

Optional: This adds user feedback. Extension works fine without it.

Step 7: Create Icons

You need 3 icon sizes. Quick option - use a placeholder:

# Create icons folder
mkdir icons

# Use any icon generator or create simple colored squares
# For now, download a brain/AI icon from:
# - https://www.flaticon.com (free with attribution)
# - Create your own with Figma/Canva

Icon requirements:

  • 16x16px (toolbar)
  • 48x48px (extensions page)
  • 128x128px (Chrome Web Store)
  • PNG format, transparent background

Quick test: Create placeholder colored squares if you want to test first.

Step 8: Load Extension in Chrome

# Make sure you're in project root
pwd  # Should show /path/to/text-enhancer-ext

In Chrome:

  1. Go to chrome://extensions
  2. Enable "Developer mode" (top-right toggle)
  3. Click "Load unpacked"
  4. Select your text-enhancer-ext folder
  5. Extension should appear with your icon

Expected: Extension loads without errors.

If it fails:

  • "Manifest is invalid": Check JSON syntax (no trailing commas)
  • "Service worker registration failed": Check file path matches manifest
  • Icons missing: Create placeholder 128x128 PNG

Verification

Test the Full Flow

  1. Setup API key:

    • Click extension icon
    • Enter OpenAI API key (starts with sk-)
    • Click "Save Key"

  2. Enhance text:

    • Visit any website (try this article!)
    • Highlight a paragraph
    • Right-click → "Enhance with GPT-5"
    • Wait 2-5 seconds

  3. Check result:

    • Extension popup opens automatically
    • Shows original and enhanced text
    • Click "Copy Enhanced Text"

You should see: Improved version of your text with better clarity.

Costs: ~$0.0001-0.001 per enhancement (depends on text length)

Common Issues

"API key not set" error

// Check storage in DevTools
chrome.storage.local.get('apiKey', (result) => {
  console.log('Stored key:', result.apiKey ? 'exists' : 'missing');
});

Fix: Re-enter API key in popup.

Service worker crashes on long text

GPT-5 API can take 10+ seconds for large text. Service workers timeout after 30 seconds.

// Add keepalive in service-worker.js
let keepAliveInterval;

chrome.contextMenus.onClicked.addListener(async (info, tab) => {
  // Start keepalive
  keepAliveInterval = setInterval(() => {
    chrome.runtime.sendMessage({ type: 'keepAlive' });
  }, 20000);  // Every 20 seconds
  
  try {
    const enhanced = await enhanceWithGPT5(selectedText);
    // ... rest of code
  } finally {
    clearInterval(keepAliveInterval);
  }
});

CORS errors

Symptom: Failed to fetch in console.

Fix: API calls MUST happen in service worker, not content script. Check your host_permissions includes OpenAI domain.

Production Checklist

Before publishing to Chrome Web Store:

  • Remove all console.log() statements
  • Add error handling for network failures
  • Test with rate limit (GPT-5 has 3 RPM free tier)
  • Add loading spinner in popup
  • Create proper 128x128 icon
  • Write privacy policy (required for API key storage)
  • Test on Windows/Mac/Linux
  • Set version to 1.0.0 in manifest

What You Learned

  • Manifest v3 requires service workers for external APIs
  • API keys stay secure in chrome.storage.local
  • Context menus are better UX than toolbar buttons for text actions
  • Service workers can timeout - use keepalive for long operations

Limitations:

  • Costs money per API call (set billing alerts)
  • Requires internet connection
  • Chrome Web Store takes 2-3 days to review
  • Can't use GPT-5 vision models (no image input in extensions yet)

Next steps:

  • Add text-to-speech for enhanced output
  • Support multiple enhancement modes (formal, casual, shorter)
  • Add local storage caching to reduce API calls
  • Create Firefox version (uses different manifest format)

Publishing to Chrome Web Store

Quick overview (full guide needs separate article):

  1. Prepare:

    • Zip extension folder: zip -r extension.zip text-enhancer-ext/
    • Create 1280x800 screenshot of popup
    • Write description (132 char max for short desc)

  2. Submit:

  3. Privacy policy required:

    • Must state you collect API keys
    • No personal data collected otherwise
    • Host on GitHub Pages (free) or include in extension description

Source Code

Complete working code for this tutorial:

Option 1: Build it yourself following these steps (recommended for learning)

Option 2: Reference implementation (if you get stuck):

  • Structure follows this guide exactly
  • All code blocks are production-ready
  • Copy/paste should work but test thoroughly

Tested on Chrome 131.x, GPT-5-turbo API, macOS Sonoma & Windows 11 Last updated: February 13, 2026 Estimated cost: ~$0.20 to build and test