Convert CRXJS HMR from filesystem-based to WebSocket-based

[jacksteamdev]

Describe the problem

Convert CRXJS HMR from filesystem-based to WebSocket-based

Problem

Currently, CRXJS implements a complex filesystem-based Hot Module Replacement (HMR) system. This approach was necessary because Chrome's Content Security Policy (CSP) for content scripts historically didn't support files served from localhost. However, this restriction has been relaxed in recent Chrome versions, making our current implementation unnecessarily complex.

References:

• [W3C WebExtensions Issue #98](Inconsistency: Default content_security_policy w3c/webextensions#98)
• [Chromium Issue #40790093](https://issues.chromium.org/issues/40790093)

Proposed Solution

We should replace our custom filesystem-based HMR with a direct connection to Vite's dev server WebSocket. This would:

1. Simplify our codebase significantly
2. Improve development performance
3. Better align with Vite's native HMR implementation
4. Reduce maintenance burden

Technical Details

Current Implementation

Our current approach involves:

• A complex file writer system that writes files to disk (fileWriter.ts, fileWriter-*.ts)
• An RxJS-based event system for tracking file changes (fileWriter-rxjs.ts)
• Custom HMR payloads and transformations (fileWriter-hmr.ts)
• A background service worker that acts as a bridge between content scripts and the dev server

Describe the proposed solution

Proposed Implementation

We can replace this with:

1. Direct WebSocket connections from content scripts to Vite's dev server
2. Utilizing Vite's native HMR protocol
3. Modifying the content script CSP as needed to allow connections to the dev server

Code Changes Required

1. Remove file writer modules:

   • fileWriter.ts
   • fileWriter-*.ts files
   • Related RxMap implementation

2. Update HMR implementation:

   • Modify plugin-hmr.ts to use Vite's WebSocket directly
   • Simplify the background script bridge or remove it entirely
   • Update the content script client to connect directly to Vite's server

3. CSP Handling:

   • Ensure content script manifest includes necessary CSP for WebSocket connections
   • Add appropriate connect-src directives for development mode

4. Tests:

   • Update all HMR-related tests to verify WebSocket-based functionality
   • Add specific tests for CSP configurations

Benefits

• Code simplification: Remove ~1000+ lines of complex code
• Maintenance: Fewer custom systems to maintain
• Performance: No filesystem operations during development
• Developer experience: Faster, more reliable HMR
• Future-proofing: Better alignment with browser standards and Vite's architecture

Verification Steps

Before implementation, we should verify:

1. That Chrome's content script CSP can be extended to allow WebSocket connections to localhost
2. The minimum Chrome version required for this feature
3. Firefox compatibility with this approach
4. Any edge cases where the filesystem approach might still be needed

Implementation Plan

1. Create a proof-of-concept branch demonstrating direct WebSocket connection
2. Document CSP requirements and browser compatibility
3. Implement core WebSocket-based HMR functionality
4. Update tests
5. Create migration documentation for any breaking changes
6. Release as a major version update

Additional Context

This change represents a significant simplification of our architecture. The file writer code is one of the most complex parts of CRXJS, and removing it would make the codebase more maintainable.

Key files to examine:

• packages/vite-plugin/src/node/fileWriter.ts
• packages/vite-plugin/src/node/fileWriter-hmr.ts
• packages/vite-plugin/src/node/fileWriter-rxjs.ts
• packages/vite-plugin/src/node/plugin-hmr.ts

Alternatives considered

Leave it as-is, but the ad hoc nature of the file writer solution leaves CRXJS open to regressions. Fixing this closes #971

Importance

nice to have

[github-actions]

⚠️ Important Notice: CRXJS is seeking new maintainers.

• New issues and PRs may not receive immediate attention
• A new maintenance team must establish itself by March 31, 2025 or this repository will be archived on June 1, 2025
• Learn more about the transition

---

This is an automated message. Please do not reply to this comment.