Development Setup & Contribution

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CONTRIBUTING.md
• package.json
• wxt.config.ts
• AGENTS.md

Refined GitHub Projects is a browser extension built using the WXT framework, React 19, and TypeScript. It is designed to enhance GitHub Projects V2 by providing bulk operations such as editing, closing, deleting, and deep duplicating items directly from the table view. The extension operates entirely within the browser, communicating directly with the GitHub GraphQL API using a locally stored Personal Access Token (PAT).

The project follows a modular architecture where the UI is injected into the GitHub DOM via content scripts, while heavy lifting—including sensitive API mutations—is handled by background service workers. This structure ensures that mutations are queued sequentially to avoid GitHub rate limits and safety triggers.

Sources: README.md:1-25, AGENTS.md:5-10, wxt.config.ts:1-15

Environment Prerequisites

Developing for Refined GitHub Projects requires a specific environment to match the Continuous Integration (CI) pipeline and ensure build stability.

Requirement	Specification	Description
Node.js	Version 25+	Required to match CI environment.
Package Manager	pnpm 10.32.1	Specified in the packageManager field of package.json.
Framework	WXT	Framework for cross-browser Manifest V3 development.
UI Library	React 19 / Primer CSS	Used for building native-feeling GitHub UI components.

Sources: package.json:4-5, AGENTS.md:13-16

Local Development Workflow

The project uses pnpm for dependency management and WXT for the build pipeline. After cloning the repository, developers must initialize the environment to generate necessary types.

# Install dependencies and generate .wxt/ types
pnpm install

# Start development server with hot reload
pnpm dev

# Run type checking (required for PRs)
pnpm typecheck

The pnpm dev command starts a WXT development server on port 3000. It typically auto-opens a Chromium-based browser with the extension pre-loaded. In cloud or headless environments, the extension must be loaded manually via chrome://extensions using the dist/chrome-mv3-dev folder.

Sources: CONTRIBUTING.md:3-8, AGENTS.md:13-25

Build Commands

The project supports multi-browser builds through WXT.

Command	Output Directory
pnpm build	dist/chrome-mv3 (Default)
pnpm build:firefox	dist/firefox-mv2 or mv3
pnpm build:edge	dist/edge-mv3

Sources: package.json:7-12, wxt.config.ts:60-90

Architecture and Data Flow

The extension relies on a strict separation of concerns between the Content Script and the Background Service Worker.

Communication Flow

The content script is responsible for DOM observation and UI injection within a Shadow DOM. However, it is strictly forbidden from making direct API calls to GitHub. All mutations must be sent as messages to the Background Worker.

The diagram shows the asynchronous messaging relationship between the UI layer and the execution layer. Sources: README.md:214-230, CONTRIBUTING.md:13-15

Critical Contribution Rules

To maintain the safety of user accounts and ensure compatibility with GitHub's anti-abuse systems, contributors must adhere to several non-negotiable technical constraints.

Rate-Limit Safety

GitHub's API will issue a 403 Abuse alert and potentially ban a Personal Access Token (PAT) if multiple mutations are fired concurrently.

• No Promise.all(): Never use Promise.all() for GraphQL mutations.
• Sequential Execution: All mutations must run through the sequential queue located in lib/queue.ts.
• Mandatory Delay: Every content-creating mutation must be followed by await sleep(1000) to maintain a 1-second buffer.

Sources: CONTRIBUTING.md:10-20, README.md:234-237

Implementation Guidelines

• UI Anchoring: Do not anchor injected UI elements to volatile CSS class names. Instead, use data-testid attributes or ARIA labels.
• Shadow DOM: Injected UI must be isolated via Shadow DOM to prevent style clashes with GitHub's native CSS.
• Immutable Patterns: Use immutable patterns when handling state; create new objects rather than mutating in place.
• File Size: Maintain small, readable files. The target is under 400 lines, with a hard limit of 800 lines per file.

Sources: CONTRIBUTING.md:23-28, README.md:238-241

Project Structure

The project was refactored in version 0.1.2 to standardize file organization.

Directory	Content Description
src/entries/	Entry points for background, content scripts, and popups.
src/components/	Reusable React components (Bulk modals, UI primitives).
src/lib/	Core logic, GraphQL queries/mutations, and storage utilities.
static/	Public assets and icons.
dist/	Compiled extension output.

Sources: CHANGELOG.md:82-86, wxt.config.ts:4-10

Pull Request Requirements

Before a Pull Request is submitted, it must meet the following automated and manual criteria:

1. Type Safety: pnpm typecheck must pass with zero errors.
2. Conventional Commits: Use messages like feat: my feature or fix: bug description.
3. API Origin: Verify that no GitHub API calls originate from content scripts.
4. Sequential Logic: Verify that all new mutations utilize the background queue and include the mandatory sleep delay.

Sources: CONTRIBUTING.md:10-18, README.md:246-252

The "Development Setup & Contribution" guide ensures that developers can effectively build and extend Refined GitHub Projects while respecting the strict architectural boundaries required for browser extension security and GitHub API compliance. Summary: README.md:245-260.