NoobHeaders 🎓

Simple, privacy-focused, local-first browser extension to modify HTTP headers. No ads, no tracking. Built for developers and noobs 🚀

✨ Features

• 🎯 Multiple Profiles: Create and switch between different header configurations
• 🔧 Request & Response Headers: Modify both request and response headers
• 🎨 Smart Filters: Apply headers to specific URLs or domains
• 📦 Import/Export: Share configurations or backup your profiles
• 🔒 Privacy First: No ads, no tracking, no analytics. Your data stays on your device
• 🌍 Open Source: Built in the open on GitHub
• ⚡ Lightweight: Fast and efficient with minimal permissions
• 🎓 Noob Friendly: Straightforward UI designed for developers and beginners

🚀 Installation

Chrome Web Store

Available on the Chrome Web Store: NoobHeaders — Chrome

Firefox Add-ons

Available on Mozilla Add-ons: NoobHeaders — Firefox

Manual Installation

Download from Releases (recommended)

Download the packaged extensions from GitHub Releases (the latest link points to the most recent published release):

• Chrome (ZIP): noobheaders-chrome.zip
• Firefox (ZIP): noobheaders-firefox.zip

Installation

1. Unzip the downloaded archive.
2. Chrome: do not import the ZIP directly. Open chrome://extensions/, enable Developer mode, click Load unpacked, and select the unzipped folder.
3. Firefox: open about:debugging#/runtime/this-firefox, click Load Temporary Add-on, and select the manifest.json file inside the unzipped folder.

Tip: When available, prefer installing from the Chrome Web Store or Firefox Add-ons to receive automatic updates.

📖 Usage

Creating Your First Profile

1. Click the extension icon in your toolbar
2. The default profile is already created
3. Click "Add Header" to add a new header
4. Configure:
   • Type: Request or Response
   • Name: Header name (e.g., User-Agent, Access-Control-Allow-Origin)
   • Value: Header value (or leave empty to remove the header)
5. Switch the profile on (its toggle in the profile list) and turn on Enable header modifications

A profile's headers are applied only when the profile is switched on. Several profiles can be on at the same time; when they set the same header, the selected profile (the one being edited) wins. Clicking a profile name only selects it for editing.

Using Filters

Filters allow you to apply headers only to specific requests:

• Domain: example.com matches the domain and all its subdomains
• URL Pattern: * is a wildcard and the whole URL must match (e.g., *://example.com/api/*). Without a scheme any scheme matches, *.example.com also matches example.com, and a pattern without a path matches every path (e.g., localhost:3000)

The type is detected automatically. When a profile has several filters, headers apply if any filter matches. Invalid filters are highlighted and never widen the scope.

Managing Profiles

• Create: Click the ➕ button next to the profile list
• Select: Click a profile name to edit it
• Rename: Click "Rename" button
• Duplicate: Click "Duplicate" to copy the current profile
• Delete: Click the 🗑️ button (requires at least 2 profiles)

Import/Export

• Export: Click "Export Profiles" to save all profiles as JSON
• Import: Click "Import Profiles" to load profiles from a JSON file

🛠️ Development

Prerequisites

• Node.js 22+
• pnpm 9+

Project Structure

noobheaders/
├── src/                 # TypeScript source files
│   ├── types/          # Type definitions
│   │   └── index.ts    # Shared interfaces (Profile, Header, Filter)
│   ├── background.ts   # Service worker with type safety
│   ├── popup.ts        # Main UI logic
│   ├── options.ts      # Options page
│   └── i18n.ts         # Internationalization helper
├── dist/               # Compiled JavaScript (generated)
├── packages/           # Packaged extensions (generated)
├── icons/              # Extension icons
├── _locales/           # Translations (en, fr, es, de, it, pt_BR, ru, zh_CN, ja, ko)
└── scripts/            # Build and package scripts

Setup

# Install dependencies
pnpm install

# Build TypeScript to JavaScript
pnpm build

# Build in development mode (with sourcemaps)
pnpm build:dev

# Build and watch for changes
pnpm build:watch

# Generate icons
pnpm run icons

# Run tests
pnpm test

# Lint code
pnpm run lint

# Format code
pnpm run format

# Check everything (build + lint + tests)
pnpm run check

# Package for distribution
pnpm run package

TypeScript Benefits

The project uses TypeScript for:

• Type Safety: Catch errors at compile time
• Better IDE Support: Autocomplete and inline documentation
• Refactoring Confidence: Safe rename and find references
• Clear Interfaces: Well-defined data structures
• Fewer Runtime Bugs: Static type checking prevents common mistakes

🧪 Testing

Run all tests:

pnpm test

Run E2E tests:

pnpm exec playwright install chromium   # first time only
pnpm test:e2e

• e2e/flows: every UI flow (popup, profiles, headers, filters, options, import/export, persistence, all UI languages) plus real requests, in Chromium.
• e2e/engine: header engine flows (real request/response headers, filters, priorities, badge, auto-switch) driven from the extension background, in Chromium and Firefox. Firefox does not let automation drive moz-extension:// pages, so its UI is covered by the Chromium run (same HTML/JS).

Run a single browser:

pnpm test:e2e:chromium
FIREFOX_BIN=/path/to/firefox pnpm test:e2e:firefox   # stock Firefox, driven through WebDriver BiDi

On Linux without a display, prefix the command with xvfb-run -a (Chromium loads extensions in headed mode).

Run Firefox manual validation:

pnpm test:firefox

Tests include:

• Unit tests for core functionality
• E2E tests with Playwright: UI flows in Chromium, header engine flows in Chromium (declarativeNetRequest) and Firefox (webRequest)
• Firefox manual validation through web-ext
• Manifest validation
• i18n completeness

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details.

Quick Start

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run checks: pnpm run check
5. Commit: git commit -m 'Add amazing feature'
6. Push: git push origin feature/amazing-feature
7. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with help from Claude AI by Anthropic
• Inspired by ModHeader and other header modification extensions
• Icons generated using Sharp

🔗 Links

• GitHub Repository
• Issue Tracker
• Changelog
• Contributing Guide

---

Made with 💜 by BioSs54 • No ads, no tracking, just headers 🎓