|
| 1 | +Shared code used by the MV3 browser extension (and previously MV2, now deprecated). Contains the storage abstraction layer, popup UI, devtools panel, custom elements (in-page widgets), and shared constants/types. |
| 2 | + |
| 3 | +# Code Organization |
| 4 | + |
| 5 | +## Core Modules (`src/`) |
| 6 | + |
| 7 | +- **`storage.ts`** — Abstraction over `chrome.storage.local`. Provides CRUD operations (`saveRecord`, `getRecord`, `removeRecord`, `getAllRecords`) and a reactive change listener (`onRecordChange`) with filtering by change type, key, and value. All extension storage access should go through this module. |
| 8 | +- **`rulesStore.ts`** — Rule/group retrieval layer built on top of `storage.ts`. Provides `getRules`, `getGroups`, `getEnabledRules` (filters by status and group status), `onRuleOrGroupChange` (reactive listener that only fires on meaningful changes). |
| 9 | +- **`constants.ts`** — Message action constants (`EXTENSION_MESSAGES`, `CLIENT_MESSAGES`, `APP_MESSAGES`), storage keys, rule title mappings, and the `PUBLIC_NAMESPACE` (`__REQUESTLY__`). |
| 10 | +- **`types.ts`** — Core extension types: `Rule`, `Group`, `RuleType`, `ObjectType`, `Status`, `SourceOperator`, `SourceKey`, DNR-related types (`UpdateDynamicRuleOptions`). |
| 11 | +- **`config.ts`** — Runtime config (log level). |
| 12 | +- **`eventUtils.ts`** — Event tracking utility helpers. |
| 13 | +- **`utils.ts`** — General-purpose utility functions. |
| 14 | + |
| 15 | +## Popup (`src/popup/`) |
| 16 | + |
| 17 | +The extension popup UI — a standalone React app (Ant Design dark theme) rendered in the popup window. |
| 18 | + |
| 19 | +- Entry point: `index.tsx` — Renders `<Popup>` inside `RecordsProvider` and Ant Design `ConfigProvider`. |
| 20 | +- **`components/Popup/`** — Main popup component with header and tab navigation. |
| 21 | +- **`components/PopupTabs/`** — Tab navigation (recent rules, pinned rules, executed rules, session recording). |
| 22 | +- **`components/ExecutedRules/`** — Shows rules that fired on the current tab. |
| 23 | +- **`components/RecentRecords/`**, **`PinnedRecords/`** — Rule lists with pin/unpin actions. |
| 24 | +- **`components/SessionRecording/`** — Session recording controls. |
| 25 | +- **`components/ApiClientContainer/`** — API client entry point in popup. |
| 26 | +- **`components/DesktopAppProxy/`** — Desktop app connection status and controls. |
| 27 | +- **`components/HttpsRuleOptions/`** — HTTPS rule configuration. |
| 28 | +- **`contexts/RecordsContext/`** — React context + reducer for managing records state (rules, groups, pinned items) in the popup. |
| 29 | + |
| 30 | +## Devtools Panel (`src/devtools/`) |
| 31 | + |
| 32 | +Chrome DevTools panel integration — adds a "Requestly" panel to Chrome DevTools. |
| 33 | + |
| 34 | +- **`devtools.js`** — Panel registration via `chrome.devtools.panels.create`. Firefox gets plain text title; Chrome/others get emoji prefix. |
| 35 | +- **`index.tsx`** — Devtools panel React app entry point. |
| 36 | +- **`containers/network/`** — Network log viewer with request/response details, headers, payload tabs, and filtering toolbars. |
| 37 | +- **`containers/executions/`** — Rule execution log viewer showing which rules were applied. |
| 38 | +- **`containers/analytics-inspector/`** — Analytics event inspector for debugging third-party tracking. |
| 39 | +- **`components/`** — Shared devtools UI components (resource type filter, icon button, empty state placeholder). |
| 40 | + |
| 41 | +## Custom Elements (`src/custom-elements/`) |
| 42 | + |
| 43 | +Web Components (Custom Elements) injected into target pages for in-page UI: |
| 44 | + |
| 45 | +- **`toast/`** — Toast notification widget. |
| 46 | +- **`test-rule-widget/`** — Widgets shown during rule testing: |
| 47 | + - `explicit-test-rule-widget/` — Shown when user explicitly tests a rule. |
| 48 | + - `implicit-test-rule-widget/` — Shown for automatic rule testing feedback. |
| 49 | +- **`session-recording-widgets/`** — Session recording UI: |
| 50 | + - `manual-mode-widget/` — Controls for manual recording. |
| 51 | + - `auto-mode-widget/` — Controls for auto recording. |
| 52 | + - `draft-session-viewer/` — Preview of recorded session. |
| 53 | + - `post-session-save-widget/` — Post-save confirmation widget. |
| 54 | +- **`abstract-classes/draggable-widget.ts`** — Base class for draggable floating widgets. |
| 55 | + |
| 56 | +All custom elements are registered in `index.ts`. |
| 57 | + |
| 58 | +# Build System |
| 59 | + |
| 60 | +- **Bundler**: Rollup (`rollup.config.js`) |
| 61 | +- **Build command**: `npm run build` (output to `dist/`) |
| 62 | +- **Dependencies**: React 18, Ant Design 5, CodeMirror 6, `@devtools-ds/*` for devtools UI, `@requestly/analytics-vendors` (local package). |
| 63 | +- **Preprocessor**: Uses PostCSS + Sass for styles. |
| 64 | +- **Pre-install hook**: Builds the analytics vendor package via `scripts/build-analytics-vendor.sh`. |
| 65 | + |
| 66 | +# How MV3 Depends on Common |
| 67 | + |
| 68 | +The MV3 extension imports from this package as `common/*` (resolved at build time to `../common/src/*`). Key imports: |
| 69 | +- `common/storage` — Storage abstraction |
| 70 | +- `common/rulesStore` — Rule retrieval and change listeners |
| 71 | +- `common/constants` — Message types and storage keys |
| 72 | +- `common/types` — TypeScript type definitions |
| 73 | +- `common/config` — Runtime config |
| 74 | + |
| 75 | +The popup and devtools UIs are built separately by this package's Rollup config and output as HTML/JS bundles that the MV3 extension includes in its `dist/`. |
| 76 | + |
| 77 | +# Development |
| 78 | + |
| 79 | +- `npm run build` — Full build |
| 80 | +- `npm run watch` — Rollup watch mode |
| 81 | +- Changes here require rebuilding: from `../mv3/`, run `npm run build:common` or `npm run build` (which does both) |
0 commit comments