How ipfs/ipfs-companion works
Project type and purpose
• This is a browser extension (“IPFS Companion”) that integrates a locally‐running IPFS node into Chromium‐ and Firefox‐based browsers. It implements content scripts, background scripts, popup and options UIs, and landing‐page handlers to detect and redirect IPFS resources, bridge protocol handlers, and communicate with the IPFS API and gateway.
File‐structure analysis
• Top‐level build & config: .babelrc, webpack.config.js, Dockerfile, Makefile, CI workflows under .github/workflows, and package.json/tsconfig.json.
• add-on/: the entire WebExtension code. Inside it, subdirectories for:
• _locales/ – translations
• manifest.*.json – browser‐specific manifests (MV2 & MV3)
• src/background/ – background script entry point
• src/contentScripts/ – content scripts injected into pages
• src/lib/ – core logic modules (IPFS client, redirect‐handler, context menus, state, telemetry)
• src/popup/ – browser action UI (HTML/CSS/JS)
• src/options/ – options page UI and forms
• src/landing-pages/ – built‐in permission and welcome pages
• test/: functional & e2e tests using Mocha, with mocks for WebExtension APIs.
• docs/: architecture notes, MV3 migration guide, release & localization docs.
README insights
• Describes the extension’s features: intercepting IPFS paths, DNSLink resolution, x-ipfs-path header handling, browser‐action menu, right‐click import, toggles.
• Mentions dependency on a local IPFS daemon (API & gateway), and optional public‐gateway fallbacks or external Web UI.
Main components & interactions
a. Components
• Browser Extension (WebExtension host)
• Background Script – central orchestrator, listens for WebRequest events, orchestrates redirects, talks to IPFS API, maintains state.
• Content Scripts – e.g., linkifyDOM.js for making plaintext links clickable, injected into web pages.
• Popup UI – the browser‐action menu (popup/browser-action/...) for user controls, status, import/pin actions.
• Options Page – React-style forms for preferences, gateway settings, experiments toggles.
• Landing Pages – built‐in HTML pages for permission requests, welcome screen.
• Lib Modules – shared business logic: IPFS client abstractions, redirect‐handlers, context‐menu builders, state management, telemetry.
• Manifest Files – configuration of permissions, background vs. content scripts, protocol handlers.
• External Services
• Local IPFS Daemon API (HTTP API, typically localhost:5001)
• Local IPFS Gateway (HTTP Gateway, typically localhost:8080)
• DNSLink DNS records lookup (via standard DNS and/or public gateways)
• Optional Public Gateways (for fallback) and IPFS Web UI dashboard
• Dev & CI Tooling
• Webpack/Babel build pipeline producing the extension bundle
• Mocha/E2E tests (via test/e2e and test/functional)
• Docker / docker‐compose for test environments
• Localization pipeline (.tx, scripts/new-locale-key.sh)
b. Relationships & data flows
• User clicks browser‐action → Popup UI sends message → Background Script queries state → optionally calls IPFS API or toggles redirect → responds to Popup.
• WebRequest event (page navigating to /ipfs/{CID}) → Background Script intercepts → checks with IPFS client lib → rewrites URL to gateway subdomain → browser reloads page at new URL.
• Content Script scans page DOM → finds plaintext IPFS links → posts message to Background Script → rewrites anchor href to ipfs:// or redirect URL.
• Options Page reads/writes preferences → persists in browser storage via Background Script and lib/state.
• Telemetry events emitted from lib modules → sent to telemetry endpoint if enabled.
• DNSLink resolution chain: DNS lookup → determine IPNS record → redirect to localhost:8080/ipns/....
c. Architectural patterns & design principles
• Modular “lib” layer for core logic, decoupled from UI and WebExtension APIs
• Event‐driven, message‐passing architecture (WebExtension messaging)
• Separation of concerns: background orchestrates, content scripts modify pages, UIs handle user interactions
• MV3‐compatible manifests with service worker vs. MV2 background scripts
• Feature toggles and experiments managed in a central state store
d. Key technologies & frameworks
• JavaScript/TypeScript, ES6+ transpiled by Babel
• Webpack for bundling
• Mocha + Chai for tests, Puppeteer/E2E harness
• WebExtension APIs (browser.*) for background, storage, runtime, webRequest
• Localization via Chrome‐style _locales
• Shell scripts and Node scripts in scripts/ for asset generation and CI hooks
Final touches
• Lay out components logically: Extension on left, Local IPFS in center, External network on right.
• Important ports (5001, 8080) and protocol handlers (ipfs://, ipns://).
• Manifest configuration as the “glue” that wires scripts to extension events.