Minimal Cookie Guard

A production-ready Chrome Extension that automatically rejects optional cookies and accepts only necessary cookies when visiting websites. Built with Manifest V3, Vite, React 18, and TypeScript.

Features

• Automatic detection and dismissal of cookie consent banners
• Heuristic support for OneTrust, Cookiebot, TrustArc, and generic banners
• Per-domain override controls
• Global enable/disable toggle
• Clean popup UI with status reporting
• Zero external UI dependencies
• Minimal permission footprint

Project Structure

src/
  background/index.ts       Service worker: tab events, script injection
  content/
    index.ts                Content script entry: MutationObserver + retry logic
    cookieHandler.ts        Banner detection and button clicking
  popup/
    App.tsx                 React popup UI with toggle controls
    ErrorBoundary.tsx       Error boundary with user-friendly fallback
    main.tsx                React entry point
    Popup.css               Standalone popup styles
  lib/
    storage.ts              chrome.storage.sync typed abstraction
    domUtils.ts             DOM visibility and element helpers
    keywordMatcher.ts       Case-insensitive keyword matching engine
  manifest.json             Manifest V3 configuration
public/
  icons/                    Extension icons (16, 32, 48, 128)
popup.html                  Popup HTML shell
vite.config.ts              Multi-target Vite build config

Prerequisites

• Node.js 18+
• npm 9+ or pnpm

Getting Started

Install Dependencies

npm install

Build for Production

npm run build

This runs a three-stage Vite build:

1. Popup (React app with HTML entry)
2. Content script (IIFE bundle)
3. Background service worker (ES module)

The final output lands in dist/.

Development (Watch Mode)

npm run dev

Rebuilds automatically when source files change.

Load in Chrome

1. Open chrome://extensions/
2. Enable "Developer mode" (top-right toggle)
3. Click "Load unpacked"
4. Select the dist/ folder
5. The shield icon appears in your toolbar

Testing Changes

After rebuilding, return to chrome://extensions/ and click the refresh icon on the Minimal Cookie Guard card. Then reload the target webpage.

Architecture Decisions

MutationObserver over polling. The content script observes DOM mutations instead of polling, which avoids performance overhead. A debounce window (500ms) collapses rapid mutations into a single scan. The observer disconnects itself after a successful action.

Heuristic detection over fragile selectors. Rather than hardcoding CSS selectors for specific consent platforms, the extension matches button text against a keyword list. This approach survives platform UI updates better than selector-based strategies.

Three-pass Vite build. Chrome extensions require different module formats for each context: IIFE for content scripts (no ES module support in page context), ES modules for the service worker, and standard Vite output for the popup. The build script orchestrates all three passes.

Minimal permissions. The extension requests only storage, activeTab, and scripting. The <all_urls> host permission is required for chrome.scripting.executeScript to inject content scripts on any domain.

Permissions Explained

Permission	Reason
storage	Persist user preferences via chrome.storage.sync
activeTab	Read the current tab URL for per-domain controls
scripting	Programmatically inject the content script
<all_urls>	Allow injection on any website the user visits

Chrome Web Store Submission

Before submitting:

1. Replace placeholder SVG icons in public/icons/ with production PNG artwork at 16, 32, 48, and 128px
2. Update version in src/manifest.json and package.json
3. Include the privacy statement (see PRIVACY.md)
4. Create promotional screenshots (1280x800 or 640x400)
5. Write a store description highlighting the privacy-first approach
6. Zip the contents of dist/ (not the folder itself) for upload

Clean Build

npm run clean

Removes the dist/ directory.

License

MIT