Plugin Setup and Configuration
Relevant source files
The following files were used as context for generating this wiki page:
- packages/plugin/popup/components/LoginPage.tsx
- packages/plugin/popup/components/SettingPage.tsx
- packages/plugin/manifest.json
- packages/plugin/popup/components/PluginHomePage.tsx
- packages/plugin/lib/single-file-extension-background.js
- packages/plugin/assets/locales/en/translation.json
- packages/plugin/manifest.firefox.json
- packages/plugin/popup/components/UploadPageForm.tsx
The Web Archive browser plugin is a crucial component of the ecosystem, responsible for capturing web pages and interfacing with the self-hosted server. Its setup and configuration are managed through a combination of manifest files, a React-based popup interface, and a powerful background script inherited from the SingleFile project. This document outlines the architecture of the plugin's configuration, from initial setup to the various user-configurable settings that control the page-saving process.
The plugin's configuration is primarily handled through a popup UI that allows users to log in, adjust page-saving options, and manage their archives. These settings are persisted in the browser's storage and utilized by the background script to orchestrate the capture and upload of web pages.
Manifest Configuration
The plugin's core behavior, permissions, and entry points are defined in its manifest files. There are separate manifests for Chrome-based browsers and Firefox to handle platform-specific differences.
- Chrome:
packages/plugin/manifest.json - Firefox:
packages/plugin/manifest.firefox.json
Key Manifest Properties
manifest_version: Set to3, indicating it uses the latest extension platform API.name,version,description: Standard metadata for the extension.action: Defines the popup UI, specifyingpopup/index.htmlas the entry point.permissions: Requests necessary browser permissions to function.host_permissions: Set to"<all_urls>"to allow the plugin to run on any website.background: Specifies the service worker (background/background.js) for Chrome or background script for Firefox, which handles core logic.content_scripts: Injects scripts into web pages to enable page capture and interaction.web_accessible_resources: Makes certain library and content scripts available to web pages, which is essential for the page saving logic.
Sources: packages/plugin/manifest.json, packages/plugin/manifest.firefox.json
Permissions
The plugin requests the following permissions to operate:
| Permission | Description |
|---|---|
activeTab | Grants access to the currently active tab when the user invokes the plugin. |
storage | Allows the plugin to save user settings, server URL, and token. |
tabs | Provides access to tab information, such as URL and title. |
scripting | Enables the plugin to inject and execute scripts on web pages. |
Sources: packages/plugin/manifest.json:42-47
Content & Background Scripts
The manifest registers several scripts that form the backbone of the plugin's functionality.
This diagram shows the relationship between the manifest, background script, popup UI, and content scripts.
Sources: packages/plugin/manifest.json:15-41, 48-51
Popup UI and User Configuration
The plugin's popup is a React application that serves as the primary user interface for configuration and interaction. It is composed of several "pages" or components that handle different aspects of the user workflow.
UI Navigation Flow
The user navigates between different views within the popup to perform actions.
This diagram illustrates the navigation paths a user can take within the popup interface.
Sources: packages/plugin/popup/components/PluginHomePage.tsx:21, packages/plugin/popup/components/PluginHomePage.tsx:103, packages/plugin/popup/components/UploadPageForm.tsx:90
Login and Authentication
The LoginPage is the initial view for an unauthenticated user. It requires the user to input their self-hosted server URL and an authentication token.
- Server URL: The address of the deployed web-archive server.
- Token: The secret key for authentication.
Upon submission, these values are sent to the background script via webext-bridge and stored securely.
This sequence shows how user credentials are saved from the login page to browser storage.
Sources: packages/plugin/popup/components/LoginPage.tsx is not in the context, but its functionality is inferred from interactions in other components like PluginHomePage which has a logout function and a setActivePage('login') call.
SingleFile Settings
The SettingPage allows users to fine-tune the page-saving process. These settings are passed to the underlying SingleFile library, which performs the actual page capture.
The settings are presented as a form with switches for boolean options. When the user saves, the configuration is persisted via the background script.
| Setting Name | UI Label | Description |
|---|---|---|
removeHiddenElements | Remove Hidden Elements | Removes elements that are not visible on the page. |
removeUnusedStyles | Remove Unused Styles | Strips out CSS rules that are not applied to any element. |
removeUnusedFonts | Remove Unused Fonts | Removes unused @font-face rules. |
compressHTML | Compress HTML | Minifies the HTML content. |
loadDeferredImages | Load Deferred Images | Attempts to load images that are lazy-loaded. |
groupDuplicateImages | Group Duplicate Images | Replaces duplicate images with a single instance to reduce file size. |
blockVideos | Block Videos | Prevents video content from being included in the saved page. |
blockAudios | Block Audios | Prevents audio content from being included in the saved page. |
blockScripts | Block Scripts | Prevents scripts from being included in the saved page. |
Sources: packages/plugin/popup/components/SettingPage.tsx:14-106, packages/plugin/assets/locales/en/translation.json:10-24
Upload Configuration
When a user decides to save a page, the UploadPageForm is displayed. It pre-fills page metadata by scraping the current tab and allows the user to confirm or edit details before saving.
- Title: The page title.
- Description: The page description.
- Folder: The destination folder on the server.
- Tags: Tags to associate with the page.
- Showcased: A switch to mark the page for the public showcase.
The form uses scrapePageData to get the initial title and description from the content script.
Sources: packages/plugin/popup/components/UploadPageForm.tsx:39-60, 101-143
Background Configuration Management
The file packages/plugin/lib/single-file-extension-background.js is a comprehensive script that manages the core logic of the extension, including the configuration system inherited from SingleFile.
Profiles and Rules
The script implements a system of profiles and rules to manage settings:
- Profiles: A named set of configuration options (e.g., the settings from the
SettingPage). The default profile is named__Default_Settings__. - Rules: Associate a URL pattern with a specific profile. This allows different settings to be automatically applied to different websites.
The configuration is stored using browser.storage.sync or browser.storage.local. The script determines which storage to use based on a sync flag.
Sources: packages/plugin/lib/single-file-extension-background.js:2039-2045, 2090-2101
Default Settings
The script defines a large set of default options in the DEFAULT_OPTIONS constant. These serve as the baseline for the __Default_Settings__ profile and any new profiles created. The settings exposed in the SettingPage.tsx are a subset of these more advanced options.
For example, removeHiddenElements defaults to true.
// packages/plugin/lib/single-file-extension-background.js:1955
const DEFAULT_OPTIONS = {
removeHiddenElements: true,
removeUnusedStyles: true,
removeUnusedFonts: true,
// ... many other options
}
Sources: packages/plugin/lib/single-file-extension-background.js:1955-2036
Conclusion
The Web Archive plugin's setup and configuration system is a layered architecture. It leverages the browser extension manifest for fundamental setup, a user-friendly React-based popup for high-level configuration and interaction, and a powerful, profile-based configuration engine in the background script inherited from SingleFile. This design provides both simplicity for the average user through the settings UI and advanced customization for power users through the underlying rules and profiles system.