Resources / Architecture
Extension Architecture (MV3)
A maintainable blueprint for complex extensions—built for MV3 constraints.
Service Worker
Messaging
Storage
Build Pipeline
Accessibility
Core components
- Service worker
- Content scripts
- UI surfaces (popup, options, pages)
- Storage
- Messaging bus
Messaging & orchestration
Patterns
- When to use one-off messages vs. long-lived ports.
- Request/response contracts with typed payloads.
- Explicit error propagation with codes + context.
- Retries/backoff for flaky networks and DOM timing.
Tips
- Centralize orchestration in the SW; keep CS lean.
- Gate actions behind explicit user gestures.
- Log message failures with trace IDs for debugging.
State & storage
Choices
chrome.storage(sync/local) vs. IndexedDB.- Sync quotas and fallbacks to local.
- Serialization and schema migrations.
Practices
- Version keys; run migrations on SW startup.
- Minimize PII; scrub sensitive fields.
- Cache with TTL; invalidate on auth/role changes.
Build pipeline
Tooling
- TypeScript + bundling (Vite/Webpack) with code-splitting.
- Dynamic imports for UI surfaces.
- Environment gates, feature flags, i18n.
Testing
- Unit + integration + e2e (Jest/Playwright).
- Mock Chrome APIs for deterministic tests.
- Lighthouse budgets in CI.
UX & accessibility
Accessibility
- Keyboard navigation & focus management.
- Color contrast + reduced motion support.
- i18n/l10n for copy and dates.
UI guidance
- Short paths to value; clear empty states.
- Non-blocking background work with status.
- Retry + cancel affordances on long tasks.
Performance budgets
Targets
- Cold start: strict budget for popup/options.
- Script weight & CPU blocking thresholds.
- Network strategies & caching.
Checks
- Profile content-script injection cost.
- Measure SW activation + warmups.
- Lighthouse & custom probes in CI.
Observability
What to collect
- Error telemetry with stack + context.
- User action events & success metrics.
- PII scrubbing + retention windows.
Use it
- Alert on error rate and queue drain time.
- Correlate with performance budgets.
- Feed roadmap with real usage data.