Skip to content

README.md

Latest commit

 

History

History
85 lines (63 loc) · 4.39 KB

README.md

File metadata and controls

85 lines (63 loc) · 4.39 KB

Gitcasso browser extension

Developer quickstart

Hotreload development

  • pnpm install
  • pnpm run dev
  • open chrome://extensions
  • toggle Developer mode (top-right)
  • click "Load unpacked" (far left)
    • browser-extension/.output/chrome-mv3-dev
    • if you can't find .output, it's probably hidden, command+shift+period will show it
  • click the puzzle icon next to the url bar, then pin the Gitcasso icon

Testing and quality

  • pnpm run biome - runs biome check (lint & formatting)
  • pnpm run biome:fix - fixes most of what biome check finds
  • pnpm run compile - typechecking
  • pnpm test - vitest
  • pnpm test -- -u updates all the snapshots

Deployment

  • pnpm run build - build for mv3 for most browsers
  • pnpm run build:firefox - build mv2 specifically for Firefox

How it works

This is a WXT-based browser extension that

  • finds textarea components and decorates them with overtype and highlight.js
  • stores unposted comment drafts, and makes them easy to find via the extension popup

Entry points

graph TD
    Content[Content Script<br/>content.ts] 
    Background[Background Script<br/>background.ts]
    Popup[Popup Script<br/>popup/popup.tsx]
    
    Content -->|ENHANCED/DESTROYED<br/>CommentEvent| Background
    Popup -->|GET_OPEN_SPOTS<br/>SWITCH_TO_TAB| Background
    Background -->|GetOpenSpotsResponse<br/>spots array| Popup
    
    Background -.->|manages| Storage[Comment State Storage<br/>openSpots JsonMap]
    Content -.->|enhances| TextArea[textarea elements<br/>on web pages]
    Popup -.->|displays| UI[Extension UI<br/>list of comment spots]
    
    classDef entrypoint fill:#e1f5fe
    classDef storage fill:#f3e5f5
    classDef ui fill:#e8f5e8
    
    class Content,Background,Popup entrypoint
    class Storage storage
    class TextArea,UI ui
Loading

Every time a textarea shows up on a page, on initial load or later on, it gets passed to a list of CommentEnhancers. Each one gets a turn to say "I can enhance this box!". They show that they can enhance it by returning something non-null in the method tryToEnhance(textarea: HTMLTextAreaElement): Spot | null. Later on, that same Spot data will be used by the tableRow(spot: Spot): ReactNode method to create React components for rich formatting in the popup table.

Those Spot values get bundled up with the HTMLTextAreaElement itself into an EnhancedTextarea, which gets added to the TextareaRegistry. At some interval, draft edits get saved by the browser extension.

When the textarea gets removed from the page, the TextareaRegistry is notified so that the CommentSpot can be marked as abandoned or submitted as appropriate.

Testing

  • npm run playground gives you a test environment where you can tinker with the popup with various test data, supports hot reload
  • npm run har:view gives you recordings of various web pages which you can see with and without enhancement by the browser extension

Recording new HAR files

  • the har recordings live in tests/har, they are complete recordings of the network requests of a single page load
  • you can add or change URLs in tests/har-index.ts
  • npx playwright codegen https://github.com/login --save-storage=playwright/.auth/gh.json will store new auth tokens
    • login manually, then close the browser
    • these cookies are very sensitive! we only run this script using a test account that has no permissions or memberships to anything, recommend you do the same!
  • pnpm run har:record this records new snapshots using those auth tokens (it needs args, run it with no args for docs)
    • DO NOT COMMIT AND PUSH NEW OR CHANGED har files!
    • we try to sanitize these (see har-record.ts for details) but there may be important PII in them
    • if you need new HAR files for something, let us know and we will generate them ourselves using a dummy account
    • IF YOUR PR CHANGES OR ADDS HAR FILES WE WILL CLOSE IT. Ask for HAR files and we'll be happy to generate clean ones you can test against.