vite-vue3-browser-extension-v3

The project is built as a multi-context extension supporting various browser environments including background scripts, popups, options pages, content scripts, devtools, side panels, and offscreen pages.

Key architectural features include:

• File-Based Routing: UI routes are automatically registered based on the directory structure in src/ui/*/pages.
• Modular UI Stack: Uses Nuxt/UI v3 and shadcn-vue for components, styled with Tailwind CSS 4.
• State & Logic: Leverages Vue 3 Composition API, Pinia for state management, and custom composables for i18n, theme, and storage.
• Compatibility: Uses webext-bridge and webextension-polyfill to ensure WebExtension API compatibility across different browsers.

The project follows a strict directory structure to separate different extension contexts and shared logic:

• src/assets/: Global assets like CSS and images.
• src/background/: Background scripts handling lifecycle and install/update logic.
• src/components/: Shared Vue components.
• src/composables/: Vue composables (hooks).
• src/content-script/: Content scripts for DOM injection and page interaction.
• src/devtools/, src/offscreen/, src/side-panel/: Specialized extension contexts.
• src/stores/: Pinia stores for state management.
• src/types/: TypeScript definitions.
• src/ui/: UI entrypoints (e.g., popup, options, setup).
• src/utils/: Shared utilities (router, i18n, pinia, etc.).
• src/modules/: (Implied by architecture) Modular logic components.

The project follows a specific directory layout to manage different extension contexts and shared logic:

• src/background/: Background service worker logic.
• src/components/: Shared Vue components.
• src/composables/: Vue composables (hooks).
• src/content-script/: Content scripts that run in the context of web pages.
• src/devtools/: DevTools panel implementation.
• src/offscreen/: Offscreen documents.
• src/stores/: Pinia state management stores.
• src/ui/: UI entrypoints (e.g., popup, options).
  • src/ui/*/pages/: Uses file-based routing for UI pages.
• src/types/: TypeScript definitions.
• src/utils/: Shared utility functions.

When developing with this project, adhere to the following standards:

Development Standards:

• Use TypeScript and the Vue 3 Composition API (<script setup>).
• Use Pinia for state management and Vue Router for navigation.
• Utilize Auto-Imports for functions, stores, and components.
• Use shadcn-vue for accessible and customizable UI components.

Logic & Error Handling:

• Use composables for cross-cutting concerns like theme, i18n, and storage.
• Handle errors gracefully. When working in background or content scripts, use console.info for logging.

To create a new project using this template, use degit to scaffold the repository, install dependencies, and start the development server.

Note: The npm run dev command starts development environments for both Chrome and Firefox simultaneously.

npx degit mubaidr/vite-vue3-browser-extension-v3 my-webext
cd my-webext
npm install
npm run dev

To test your extension in Firefox:

1. Navigate to about:debugging#/runtime/this-firefox.
2. Click the Load Temporary Add-on... button.
3. Select any file located within the dist/firefox folder.

To test your extension in a Chromium-based browser:

1. Open chrome://extensions in your browser.
2. Enable Developer mode using the toggle in the top-right corner.
3. Click the Load unpacked button.
4. Select the dist/chrome directory from your project folder.

Both useBrowserSyncStorage and useBrowserLocalStorage return a promise. Because reading from chrome.storage is asynchronous, you should await this promise before relying on the data value to ensure that the initial state reflects what is actually stored in the browser, rather than just the defaultValue provided.

const { data, promise } = useBrowserSyncStorage('my_key', 'default')

// Do this to ensure 'data' is populated from storage before use
await promise
console.log(data.value) // This will be the actual stored value

The storage composables enforce type consistency to prevent corrupting stored data.

• Type Matching: When updating data, the new value must match the type of the defaultValue. If a type mismatch occurs (e.g., trying to save a string where a boolean was expected), the update will be rejected and an error will be logged.
• Deep Merging: If the defaultValue is an object, the composable performs a deep merge when loading data from storage. This allows you to add new properties to your default configuration object without losing existing user settings for older properties.
• Supported Types: The system validates types for strings, booleans, nulls, and arrays.