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.

Thank you for contributing to xBlockOrigin! This guide covers code style, quality standards, and the pull request process.

​
Code quality standards

All code must pass automated checks before being merged. Run these commands before committing: 
bunx tsc --noEmit
Use bun run check to run type checking, linting, and formatting in sequence. This is the fastest way to catch all issues.

​
Code style guidelines

​
Language preferences

xBlockOrigin uses modern JavaScript/TypeScript patterns:
  • Use Bun over Node.js - All scripts should use bun instead of node
  • Tab indentation - 4-space tabs (configured in Biome)
  • No semicolons - Biome enforces semicolon-free style
  • Latest JS/TS features - Use modern syntax over legacy patterns
  • Lowercase comments - Keep comments lowercase unless referencing proper nouns
  • Files under 200 lines - Split large files into smaller, focused modules

​
TypeScript guidelines

Follow these TypeScript best practices:
These rules are strictly enforced:
  • NEVER use any - Always specify proper types
  • NEVER use non-null assertions (!) - Handle null/undefined explicitly
  • NEVER use as type assertions - Use runtime validation with Valibot instead
Preferred patterns:
  • Prefer inline types over separate interface declarations
  • Leverage automatic type inference (avoid explicit return types when unnecessary)
  • Use Valibot schemas for runtime type validation
Example - Runtime validation instead of type assertions: 
// Bad - using 'as'
const data = response as UserData

// Good - using Valibot schema
import * as v from 'valibot'

const UserDataSchema = v.object({
	userId: v.string(),
	username: v.string()
})

const data = v.parse(UserDataSchema, response)

​
Functional programming over OOP

xBlockOrigin strongly prefers functional programming:
Classes are allowed only for pure, semantic types where per-instance state is required (e.g., User, Task).
Avoid OOP patterns:
  • No service classes (*Service, *Manager)
  • No factory classes (*Factory, *Builder)
  • No singleton patterns
Use functional modules with exported functions instead.
Example - Functional vs OOP: 
// Bad - OOP service class
class UserService {
	async muteUser(userId: string) { ... }
	async unmuteUser(userId: string) { ... }
}

// Good - Functional module
export async function muteUser(userId: string) { ... }
export async function unmuteUser(userId: string) { ... }

​
File organization

​
Naming conventions

  • PascalCase - Directories and component files (Popup/, App.tsx)
  • camelCase - Utility files and functions (cache.ts, orchestrator.ts)
  • Consistent casing within each domain

​
Directory structure principles

  1. Feature-based organization - Group by feature, not by type
  2. Colocate related code - Keep components with their styles and types
  3. No barrel exports - Import directly from source files
  4. Separate concerns - Each file should have a single responsibility
Example structure: 
Popup/
├── App.tsx                    # Main component
├── BlacklistManager.tsx       # Feature component
├── components/                # Subcomponents
│   └── UnmuteConfirmDialog.tsx
└── hooks.ts                   # Shared hooks

​
Biome configuration

The project uses Biome for linting and formatting. Key settings from biome.json:
  • Indentation: Tabs (4 spaces)
  • Line width: 80 characters
  • Quotes: Single quotes for JS, double for JSX
  • Semicolons: As needed (effectively none)
  • Trailing commas: None
  • Arrow parentheses: Always
Biome runs automatically via the lint and format scripts. Don’t fight the formatter - let Biome handle style.

​
Pull request process

1

Create a feature branch

Create a branch from main for your changes:
git checkout -b feature/your-feature-name
Use descriptive branch names:
  • feature/ - New features
  • fix/ - Bug fixes
  • refactor/ - Code refactoring
  • docs/ - Documentation changes
2

Make your changes

Follow the code style guidelines and keep commits focused:
  • One logical change per commit
  • Write clear commit messages
  • Keep files under 200 lines
  • Add comments only for complex logic
3

Run quality checks

Before committing, ensure all checks pass:
bun run check
This runs:
  1. Type checking (bunx tsc --noEmit)
  2. Linting (bunx @biomejs/biome check --fix --unsafe)
  3. Formatting (bunx @biomejs/biome format --fix)
The CI pipeline will reject PRs that don’t pass these checks.
4

Test your changes

Build and test the extension in both browsers:
bun run build
Load the extension in Chrome and Firefox to verify:
  • Functionality works as expected
  • No console errors
  • No visual regressions
5

Commit with version bump

The pre-commit hook automatically increments the major version:
git add .
git commit -m "Add feature description"
The hook will bump the version (e.g., 28.0.0 → 29.0.0) automatically.
If the hook doesn’t run, manually run: bun run setup-hooks
6

Push and create PR

Push your branch and create a pull request:
git push origin feature/your-feature-name
In your PR description:
  • Describe what changed and why
  • Include screenshots for UI changes
  • Reference any related issues
  • Note if this is a breaking change
7

Address review feedback

Respond to review comments and make requested changes:
  • Push additional commits to your branch
  • Re-run bun run check after changes
  • Update tests if functionality changed

​
Common pitfalls to avoid

Don’t:
  • Use any, as, or non-null assertions
  • Create service/factory classes
  • Add barrel exports (index.ts that re-exports everything)
  • Skip type checking or linting
  • Make files over 200 lines
  • Use node instead of bun
  • Edit files in dist/ directory
  • Commit without running quality checks
Do:
  • Use Valibot for runtime validation
  • Write functional modules with exported functions
  • Import directly from source files
  • Run bun run check before committing
  • Split large files into focused modules
  • Use bun for all scripts
  • Edit source files in packages/extension/src/
  • Test in both Chrome and Firefox

​
Getting help

If you need help:
  1. Check the project structure to understand the codebase
  2. Review the README.md for technical details
  3. Look at recent commits for examples of good code style
  4. Open a discussion issue before starting large changes

​
License and attribution

By contributing, you agree that your contributions will be licensed under the same license as the project. Always respect third-party licenses when adding dependencies.

Build docs developers (and LLMs) love

Get started for freeTalk to us