Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/chefnaphtha/xBlockOrigin/llms.txt

Use this file to discover all available pages before exploring further.

xBlockOrigin follows a feature-based architecture with clear separation of concerns. This guide explains the project structure and key directories.

​
Overview

The project is organized as a monorepo with the extension code in packages/extension/: 
xblockorigin/
├── packages/
│   └── extension/          # Main extension code
│       ├── src/            # Source files
│       ├── manifest.v2.json  # Firefox manifest
│       └── manifest.v3.json  # Chrome manifest
├── dist/                   # Build output (generated)
│   ├── chrome/
│   └── firefox/
├── scripts/                # Build and automation scripts
├── package.json            # Dependencies and scripts
├── biome.json             # Linting and formatting config
├── tsconfig.json          # TypeScript configuration
└── README.md

​
Source directory structure

The packages/extension/src/ directory contains all source code, organized by feature: 
src/
├── Api/                   # X.com GraphQL API integration
├── Background/            # Background service worker
├── Content/               # Content scripts and page scanners
├── Popup/                 # Preact-based popup UI
├── Storage/               # Data persistence layer
└── Utils/                 # Shared utilities

​
Api directory

Handles all communication with X.com’s GraphQL API: 
// Base GraphQL client for making authenticated requests
All API responses are validated using Valibot schemas to ensure type safety at runtime.

​
Background directory

Contains the background service worker (Chrome) or background page (Firefox):
  • index.ts - Main background script entry point
  • Handles extension lifecycle events
  • Manages communication between content scripts and popup
The background script remains minimal to reduce memory usage and improve performance.

​
Content directory

Content scripts that run on X.com pages:
FilePurpose
index.tsMain content script entry point
orchestrator.tsCoordinates user processing and muting logic
postHider.tsApplies blur overlay to posts from muted users
hiddenPostNotice.tsUI components for unhiding posts
timelineScanner.tsScans timeline for user profiles
searchScanner.tsScans search results
statusScanner.tsScans post detail pages
replyScanner.tsScans notifications and replies
profileScanner.tsScans user profile pages
extractors.tsExtract user data from DOM elements
flagInjector.tsInject country flags next to usernames
unmuteHandler.tsHandle unmute and whitelist actions
Each scanner targets specific X.com page types and uses MutationObserver to detect dynamically loaded content.
Preact-based UI components for the extension popup:

​
Main components

  • App.tsx - Root application component
  • index.tsx - Entry point that renders the app
  • hooks.ts - Custom Preact hooks

​
Feature sections

  • BlacklistManager.tsx / BlacklistSection.tsx - Country blacklist management
  • WhitelistManager.tsx / WhitelistSection.tsx - User whitelist management
  • MutedUsersSection.tsx / MutedUsersTable.tsx - Display muted users
  • Settings.tsx - Extension settings
  • Stats.tsx - Muting statistics
  • ExportButton.tsx - CSV export functionality
  • DebugPanel.tsx - Developer debugging tools

​
Subcomponents

components/
├── UnmuteConfirmDialog.tsx     # Confirmation modal for unmuting
├── UnmuteModeSelector.tsx      # Select unmute mode (all/country)
└── UnmuteProgressDisplay.tsx   # Show unmute progress

​
Static assets

  • popup.html - HTML shell for the popup
  • themes.css - Theme styles (light/dark/dim)
  • theme-loader.js - Detect and apply theme on load

​
Storage directory

Data persistence layer using Chrome storage APIs: 
// Muted users database
// Stores: username, userId, country, mutedAt timestamp
Uses chrome.storage.sync for settings (syncs across devices) and chrome.storage.local for user data.

​
Utils directory

Shared utility modules:
FilePurpose
cache.tsPersistent cache with TTL (24h for countries, 5min for following status)
rateLimit.tsAPI request queue for sequential processing
rateLimitState.tsRequest queue state management
csvExporter.tsExport muted users to CSV format
countryFlags.tsCountry name to flag emoji mapping
themeDetector.tsDetect X.com theme (light/dark/dim)
unmuteService.tsBulk unmute operations

​
Manifest files

Two manifest versions for cross-browser compatibility:

​
manifest.v3.json (Chrome/Edge)

  • Uses Manifest V3 specification
  • Service worker instead of background page
  • Required for Chrome Web Store

​
manifest.v2.json (Firefox)

  • Uses Manifest V2 specification
  • Persistent background page
  • Required for Firefox Add-ons (V3 not fully supported)
Never edit manifests directly in the dist/ directory. Always edit the source manifest files in packages/extension/.

​
Build output

The dist/ directory is generated during builds and contains browser-ready extensions: 
dist/
├── chrome/
│   ├── manifest.json       # Copied from manifest.v3.json
│   ├── content.js          # Bundled from src/Content/
│   ├── background.js       # Bundled from src/Background/
│   ├── popup.js            # Bundled from src/Popup/
│   ├── popup.html
│   ├── themes.css
│   └── theme-loader.js
└── firefox/
    └── (same structure with manifest.v2.json)
The dist/ directory is git-ignored. Always rebuild after pulling changes.

​
Naming conventions

The codebase follows these conventions:
  • PascalCase - Directories and React/Preact components (Popup/, App.tsx)
  • camelCase - Utility files and functions (cache.ts, orchestrator.ts)
  • No semicolons - Biome configuration enforces no semicolons
  • Tab indentation - 4-space tabs configured in Biome
  • Lowercase comments - Comments use lowercase for consistency

​
Architecture principles

The project follows functional programming principles:
Avoid OOP patterns like service classes or factories. Use functional modules instead.

​
Key principles

  1. Feature-based organization - Related code stays together
  2. Functional over OOP - Pure functions and modules preferred
  3. No barrel exports - Import directly from source files
  4. Files under 200 lines - Split large files into focused modules
  5. Runtime validation - Use Valibot for type safety at runtime
  6. Never use any or as - Maintain strict type safety
See the contributing guidelines for detailed code style rules.

Build docs developers (and LLMs) love

Get started for freeTalk to us