CRXJS Chrome Extension Tools

CRXJS is a toolset for building cross-browser extensions with native Hot Module Replacement (HMR) and zero-config setup. Key features include:

• Full Vite Plugin Ecosystem: Use any Vite-compatible plugins without extra setup.
• Zero Configuration: Intelligent defaults for immediate development.
• Manifest V3 Support: Built for modern Chrome extensions.
• True Hot Module Replacement (HMR): Instant UI updates that preserve extension state, including support for content scripts.
• Static Asset Import: Direct referencing of images and fonts in your code.
• Auto Web-Accessible Resources: Automatic generation of web_accessible_resources manifest entries.

This template organizes extension components into specific directories:

• src/popup/: Contains the Extension popup UI.
• src/content/: Contains Content scripts.
• manifest.config.ts: The central file for Chrome extension manifest configuration.

This template provides a pre-configured environment for developing Chrome extensions using Vue 3, TypeScript, and Vite, integrated with the CRXJS Vite plugin.

To get started, follow these steps:

1. Install dependencies using npm.
2. Run the development server for live reloading.
3. Build the project for production deployment.

npm install
npm run dev
npm run build

Content scripts share the origin of the host page. If you attempt to use a relative path like logo.svg, the browser will attempt to load it from the host page's origin (e.g., https://google.com/logo.svg) instead of your extension's directory.

To correctly load images from your extension within a content script, follow these two steps:

1. Declare the images in manifest.json: You must add the image paths to the web_accessible_resources field so the browser allows the host page to access them.
2. Use chrome.runtime.getURL: Reference the image using the chrome.runtime.getURL method to resolve the correct extension-internal URL.

To start a new project compatible with CRXJS, use the Vite scaffolding command. Follow the interactive prompts to set up your environment.

npm create vite@latest

CRXJS supports importing static assets directly into content scripts. When you import an asset, CRXJS automatically declares it as a web_accessible_resources dependency in the manifest.

Because content scripts share the origin of the host page, you must convert imported asset paths to the extension origin using chrome.runtime.getURL to ensure they load correctly.

import logo from './logo.png'
const url = chrome.runtime.getURL(logo)

For projects using React versions prior to 18, use ReactDOM.render after creating and appending a root element to the document body.

import React from 'react'
import ReactDOM from 'react-dom'
import './index.css'
import App from './App'

// Create the root element and append it to the DOM
const root = document.createElement('div')
root.id = 'crx-root'
document.body.append(root)

ReactDOM.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
  root,
)

To leverage Vite's Hot Module Replacement (HMR) while developing a popup, you must prevent the popup from closing automatically.

1. Locate the extension icon in your browser.
2. Right-click the icon.
3. Select "Inspect popup window".

This opens the popup alongside its dedicated DevTools window, allowing the popup to remain open and visible while you apply code changes.