From 302c75109a941d5d9a33623e72f1ac443ef760f3 Mon Sep 17 00:00:00 2001 From: Cezar Augusto Date: Sun, 3 Nov 2024 17:17:57 -0300 Subject: [PATCH] A bunch of updates --- docs/en/docs/commands/build.mdx | 2 +- docs/en/docs/commands/create.mdx | 15 +- docs/en/docs/commands/dev.mdx | 24 +- docs/en/docs/commands/preview.mdx | 18 +- docs/en/docs/development/_meta.json | 6 +- docs/en/docs/development/background.mdx | 77 ++++++ docs/en/docs/development/content_scripts.mdx | 81 +++++++ docs/en/docs/development/css.mdx | 43 ++-- docs/en/docs/development/icons.mdx | 186 +++++++++++---- docs/en/docs/development/javascript.mdx | 108 +++++++++ docs/en/docs/development/json.mdx | 45 ++-- docs/en/docs/development/locales.mdx | 24 +- docs/en/docs/development/scripts.mdx | 104 -------- .../development/web_accessible_resources.mdx | 225 ++++++++++++------ docs/en/docs/features/_meta.json | 2 +- docs/en/docs/features/config.mdx | 115 ++++++--- 16 files changed, 724 insertions(+), 351 deletions(-) create mode 100644 docs/en/docs/development/background.mdx create mode 100644 docs/en/docs/development/content_scripts.mdx create mode 100644 docs/en/docs/development/javascript.mdx delete mode 100644 docs/en/docs/development/scripts.mdx diff --git a/docs/en/docs/commands/build.mdx b/docs/en/docs/commands/build.mdx index 626ae8b..d9455d5 100644 --- a/docs/en/docs/commands/build.mdx +++ b/docs/en/docs/commands/build.mdx @@ -11,7 +11,7 @@ The `build` command in Extension.js is responsible for compiling your extension This command creates optimized builds for different browsers, ensuring compatibility and performance. The `build/` folder will contain subfolders for each targeted browser, each with the necessary code transforms and optimizations. -## How it Works? +## How Does It Work? During the build process, the following steps take place: diff --git a/docs/en/docs/commands/create.mdx b/docs/en/docs/commands/create.mdx index 2315d7e..3cbb9c6 100644 --- a/docs/en/docs/commands/create.mdx +++ b/docs/en/docs/commands/create.mdx @@ -1,6 +1,6 @@ import { PackageManagerTabs } from "@theme"; import { AvatarImage } from "../../../../theme/components/avatar-image"; -import {CarouselTemplates} from "../../../../theme/components/carousel-templates"; +import { CarouselTemplates } from "../../../../theme/components/carousel-templates"; @@ -12,7 +12,7 @@ and allows you to define the directory or path where the extension will be creat The command is designed to simplify the setup process for developers, providing a streamlined way to get started with cross-browser extension development. -## How it Works? +## How Does It Work? ![Create Command](https://github.com/user-attachments/assets/666c4f07-7303-4bdc-971f-9c3684adb06f) @@ -67,11 +67,11 @@ In this example, the extension is created in the `path/to/my-extension` director The `create` command accepts several arguments and flags to customize the behavior of the extension creation: -| Flag | Argument | What it does | Defaults to | -| ---------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | -| `[path or name]` | The extension path or name | If a path is defined, loads the local extension. If a name is provided, loads the extension in the current working directory. | `process.cwd()` | -| -t, --template | Name of the template used to bootstrap your extension | Bootstrap your extension using a template | [new](../getting-started/templates#template-new) | -| --install | Whether or not to auto install the template dependencies | Install dependencies and devDependencies during creation time | `true` | +| Flag | Argument | What it does | Defaults to | +| ---------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | +| `[path or name]` | The extension path or name | If a path is defined, loads the local extension. If a name is provided, loads the extension in the current working directory. | `process.cwd()` | +| -t, --template | Name of the template used to bootstrap your extension | Bootstrap your extension using a template | [new](../getting-started/templates#template-new) | +| --install | Whether or not to auto install the template dependencies | Install dependencies and devDependencies during creation time | `true` | - **Path or Name:** If a path is provided, the extension is created at that location. If a name is provided, it is created in the current working directory. - **`--template`:** Specifies the template to use when bootstrapping the extension (e.g., `react`, `typescript`). @@ -92,7 +92,6 @@ This command creates a new extension named my-new-extension using the React temp - ## Best Practices - Starting from a Template: Using a template is the fastest way to get started with browser extension development in Extension.js. diff --git a/docs/en/docs/commands/dev.mdx b/docs/en/docs/commands/dev.mdx index bb02b2c..6258674 100644 --- a/docs/en/docs/commands/dev.mdx +++ b/docs/en/docs/commands/dev.mdx @@ -9,7 +9,7 @@ import { AvatarImage } from "../../../../theme/components/avatar-image"; The `dev` command watches for changes in your extension's files, recompiles them, and reloads the extension in real-time. If you provide a URL, Extension.js will download and run the extension as if it were local. -## How it Works? +## How Does It Work? For development frameworks, it's an industry-standard practice to have a development server that watches for changes in your files and recompiles them in real time. Given the complex nature of browser extensions, the `dev` command in Extension.js handles the watch and recompile process for all the different contexts (HTML or not) of your extension. @@ -46,16 +46,16 @@ In this example, the extension is developed in the `path/to/my-extension` direct Below is a breakdown of the available flags for the `dev` command: -| Flag | Argument | What it does | Defaults to | -| ----------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | -| `[path or url]` | Extension path or remote URL | If a path is defined, it loads the local extension. If a URL is provided, it pulls the extension from a remote source and loads it as a local extension | `process.cwd()` | -| `--polyfill` | Boolean | Enables compatibility for the `browser.*` API in Chromium-based browsers | `false` | -| `--profile` | Profile path | Specifies a path to a browser profile for testing | `default` | -| `-b, --browser` | Browser to run the extension | Specifies the browser to run (`chrome`, `edge`, `firefox`, `all`) | `"chrome"` | -| `--chromium-binary` | Path to the Chromium binary | Provides the path to a custom Chromium-based browser binary [Read more](../browsers/unsupported.mdx) | `undefined` | -| `--gecko-binary` | Path to the Gecko binary | Provides the path to a custom Gecko-based browser binary [Read more](../browsers/unsupported.mdx) | `undefined` | -| `--starting-url` | URL | Starting URL for testing with the extension | `chrome://newtab` | -| `--open` | Boolean | Whether or not to automatically open the browser upon starting dev | `true` | +| Flag | Argument | What it does | Defaults to | +| ------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | +| `[path or url]` | Extension path or remote URL | If a path is defined, it loads the local extension. If a URL is provided, it pulls the extension from a remote source and loads it as a local extension | `process.cwd()` | +| `--polyfill` | Boolean | Enables compatibility for the `browser.*` API in Chromium-based browsers | `false` | +| `--profile` | Profile path | Specifies a path to a browser profile for testing | `default` | +| `-b, --browser` | Browser to run the extension | Specifies the browser to run (`chrome`, `edge`, `firefox`, `all`) | `"chrome"` | +| `--chromium-binary` | Path to the Chromium binary | Provides the path to a custom Chromium-based browser binary [Read more](../browsers/unsupported.mdx) | `undefined` | +| `--gecko-binary` | Path to the Gecko binary | Provides the path to a custom Gecko-based browser binary [Read more](../browsers/unsupported.mdx) | `undefined` | +| `--starting-url` | URL | Starting URL for testing with the extension | `chrome://newtab` | +| `--open` | Boolean | Whether or not to automatically open the browser upon starting dev | `true` | ## Examples @@ -92,7 +92,7 @@ Below is a breakdown of the available flags for the `dev` command: npm: "extension dev ./my-extension --browser firefox", pnpm: "extension dev ./my-extension --browser firefox", yarn: "extension dev ./my-extension --browser firefox", - }} + }} /> ### Running in All Browsers at Once diff --git a/docs/en/docs/commands/preview.mdx b/docs/en/docs/commands/preview.mdx index 4dbe95a..b3a65c5 100644 --- a/docs/en/docs/commands/preview.mdx +++ b/docs/en/docs/commands/preview.mdx @@ -9,7 +9,7 @@ import { AvatarImage } from "../../../../theme/components/avatar-image"; **The `preview` command allows you to run your extension in a production-like environment without making a final build.** It simulates how the extension will behave in a production browser environment. This is helpful for testing before officially deploying or building the extension. -## How it Works? +## How Does It Work? The `build` command compiles your extension and creates a production-ready package that the `preview` command can run. The `preview` command runs the production-ready package in a browser environment, allowing you to test the extension's functionality. @@ -40,14 +40,14 @@ In this example, the extension is created in the `path/to/my-extension` director ## Arguments And Flags -| Flag | Argument | What it does | Defaults to | -| ------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | -| [path or url] | The extension path or the remote extension URL | If a path is defined, previews the local extension. If a URL is provided, pulls the extension from remote source and previews it as a local extension | `process.cwd()` | -| `--profile` | Profile path | Specifies a path to a browser profile for testing | `default` | -| `-b, --browser` | Browser to run the extension | Specifies the browser to run (`chrome`, `edge`, `firefox`, `all`) | `"chrome"` | -| `--chromium-binary` | Path to the Chromium binary | Provides the path to a custom Chromium-based browser binary [Read more](../browsers/unsupported.mdx) | `undefined` | -| `--gecko-binary` | Path to the Gecko binary | Provides the path to a custom Gecko-based browser binary [Read more](../browsers/unsupported.mdx) | `undefined` | -| `--starting-url` | URL | Starting URL for testing with the extension | `chrome://newtab` | +| Flag | Argument | What it does | Defaults to | +| ------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | +| [path or url] | The extension path or the remote extension URL | If a path is defined, previews the local extension. If a URL is provided, pulls the extension from remote source and previews it as a local extension | `process.cwd()` | +| `--profile` | Profile path | Specifies a path to a browser profile for testing | `default` | +| `-b, --browser` | Browser to run the extension | Specifies the browser to run (`chrome`, `edge`, `firefox`, `all`) | `"chrome"` | +| `--chromium-binary` | Path to the Chromium binary | Provides the path to a custom Chromium-based browser binary [Read more](../browsers/unsupported.mdx) | `undefined` | +| `--gecko-binary` | Path to the Gecko binary | Provides the path to a custom Gecko-based browser binary [Read more](../browsers/unsupported.mdx) | `undefined` | +| `--starting-url` | URL | Starting URL for testing with the extension | `chrome://newtab` | ## Examples diff --git a/docs/en/docs/development/_meta.json b/docs/en/docs/development/_meta.json index ade876a..828c109 100644 --- a/docs/en/docs/development/_meta.json +++ b/docs/en/docs/development/_meta.json @@ -1,8 +1,10 @@ [ - { "name": "manifest-json", "label": "Manifest" }, + { "name": "manifest-json", "label": "manifest.json" }, { "name": "html", "label": "HTML" }, - { "name": "scripts", "label": "Scripts" }, { "name": "css", "label": "CSS" }, + { "name": "javascript", "label": "JavaScript" }, + { "name": "background", "label": "Background Scripts / Service Worker" }, + { "name": "content_scripts", "label": "Content Scripts" }, { "name": "locales", "label": "Locales" }, { "name": "json", "label": "JSON" }, { "name": "icons", "label": "Icons" }, diff --git a/docs/en/docs/development/background.mdx b/docs/en/docs/development/background.mdx new file mode 100644 index 0000000..2d90cf6 --- /dev/null +++ b/docs/en/docs/development/background.mdx @@ -0,0 +1,77 @@ +import { PackageManagerTabs } from "@theme"; +import { AvatarImage } from "../../../../theme/components/avatar-image"; + + + +# Background Scripts + +Background scripts are JavaScript files running in the background of an extension, providing persistent functionality such as handling events, storing data, and managing state. Extension.js supports background scripts in both `background.scripts` and `background.service_worker` formats, providing full control over long-lived processes within your extension. + +## How It Works? + +Extension.js handles background scripts with the following features: + +1. **Persistent Event Listeners:** Background scripts can register persistent listeners to respond to browser events, API calls, or messages from content scripts. +2. **Hot-Module Replacement (HMR):** For development, HMR is supported for background scripts declared under `background.scripts`, allowing faster feedback without restarting the extension. +3. **Service Worker Mode:** When using `background.service_worker`, the background script will run as a service worker, aligning with Manifest V3’s requirements. + +## Background Script Support + +The following fields in `manifest.json` are used to declare background scripts: + +| Manifest Field | File Type Expected | HMR Support | +| --------------------------- | ------------------ | ----------- | +| `background.service_worker` | .js, .ts, .mjs | No | +| `background.scripts` | .js, .ts, .mjs | Yes | + +## Sample Background Script Declaration + +Below is an example of how to declare a background script within the `manifest.json` file: + +```json +{ + "manifest_version": 3, + "name": "My Extension", + "version": "1.0", + "background": { + "service_worker": "./scripts/background-service-worker.js" + } +} +``` + +This configuration defines `background-service-worker.js` as a service worker, which will persist and respond to events as needed by your extension. + +## Handling Additional Background Scripts + +Place any additional background scripts that are not directly declared in `manifest.json` into the `/scripts` folder. Extension.js processes these files for inclusion in the build. + +**Example Usage:** + +```plaintext +scripts/ +└── extra-background-script.js +``` + +## Output Path + +Background scripts will be output in the following directory structure: + +```plaintext +dist/ + [browser]/ + ├── background/ + │ └── background-service-worker.js + │ └── extra-background-script.js + └── other-extension-files +``` + +## Best Practices + +- **Use Service Workers for Manifest V3 Compliance:** With Manifest V3, consider using `background.service_worker` to ensure compatibility. +- **Organize Scripts in `/scripts` Folder:** Maintain a structured `/scripts` folder for modularity and code clarity. +- **Optimize Long-Running Processes:** Background scripts should be optimized for performance, especially in service worker mode where resources are limited. + +## Next Steps + +- Learn more about structuring and using [Special Folders](../features/special-folders.mdx). +- Discover the options for managing resources and event handling with [Extension.js Background API](../features/background-api). diff --git a/docs/en/docs/development/content_scripts.mdx b/docs/en/docs/development/content_scripts.mdx new file mode 100644 index 0000000..8e4fa26 --- /dev/null +++ b/docs/en/docs/development/content_scripts.mdx @@ -0,0 +1,81 @@ +import { PackageManagerTabs } from "@theme"; +import { AvatarImage } from "../../../../theme/components/avatar-image"; + + + +# Content Scripts + +Content scripts are JavaScript files that run in the context of web pages. In Extension.js, these scripts are essential for interacting with web pages, modifying their content, and accessing page elements. Content scripts allow your extension to add custom functionality to specific pages or web applications. + +## How It Works? + +Extension.js manages content scripts by performing the following actions: + +1. **Process Script Files:** All JavaScript and CSS files declared in the `content_scripts` field of the `manifest.json` are compiled, bundled, and emitted. +2. **Inject CSS for Hot-Module Replacement (HMR):** During development, Extension.js injects CSS files dynamically to support HMR, ensuring seamless updates without a full page reload. +3. **Maintain Isolation:** Content scripts operate in an isolated environment, ensuring no direct access to the page’s JavaScript context. + +## Content Scripts Support + +The following fields in the `manifest.json` are used for declaring content scripts and related resources: + +| Manifest Field | File Type Expected | HMR Support | +| --------------------- | ------------------------- | ----------- | +| `content_scripts.js` | .js, .ts, .mjs, .tsx | Yes | +| `content_scripts.css` | .css, .scss, .less, .sass | Yes | + +## Sample Content Script Declaration + +Below is an example of how to declare content scripts within the `manifest.json` file: + +```json +{ + "manifest_version": 3, + "name": "My Extension", + "version": "1.0", + "content_scripts": [ + { + "matches": [""], + "js": ["./scripts/content-script.js"], + "css": ["./styles/content-style.css"] + } + ] +} +``` + +This configuration specifies that the `content-script.js` JavaScript file and `content-style.css` CSS file should run on all web pages. + +## Handling Additional Content Scripts + +To include additional content scripts outside the `manifest.json`, place them in the `/scripts` folder. This approach allows you to modularize your scripts for better code organization. + +**Example Usage:** + +```plaintext +scripts/ +└── extra-content-script.js +``` + +## Output Path + +Content scripts are output to the following directory: + +```plaintext +dist/ + [browser]/ + ├── content_scripts/ + │ └── content-script.js + │ └── extra-content-script.js + └── other-extension-files +``` + +## Best Practices + +- **Minimize Content Scripts:** Limit the size and complexity of content scripts to improve performance. +- **Modularize Code:** Use the `/scripts` folder to keep content scripts organized and modular. +- **Leverage HMR During Development:** Take advantage of HMR to test CSS changes dynamically without reloading the page. + +## Next Steps + +- For further details on using special folders, refer to the [Special Folders documentation](../features/special-folders.mdx). +- Learn about managing resources with [Web-Accessible Resources](../web-accessible-resources). diff --git a/docs/en/docs/development/css.mdx b/docs/en/docs/development/css.mdx index 7105bd8..ea5770c 100644 --- a/docs/en/docs/development/css.mdx +++ b/docs/en/docs/development/css.mdx @@ -5,22 +5,23 @@ import { AvatarImage } from "../../../../theme/components/avatar-image"; # CSS -In an extension, CSS files play a key role in defining the visual style of popups, options pages, new tab pages, and injected content. Extension.js ensures that CSS files defined in the `manifest.json` or included in HTML files are properly processed, supporting popular pre-processors like Sass, Less, and standard CSS. +Extension.js ensures that CSS files defined in the `manifest.json` or included in HTML files are properly processed, supporting popular pre-processors like Sass, Less, and standard CSS. These styles can be used in both `content_scripts` and HTML pages with their original extensions, making development flexible and modern. -## CSS File Support +## How Does It Work? -Extension.js offers first-class support for CSS and its pre-processor variants (e.g., `.scss`, `.sass`, `.less`). These styles can be used in both `content_scripts` and HTML pages with their original extensions, making development flexible and modern. Additionally, hot-module replacement (HMR) is supported for CSS during development, ensuring rapid feedback and live updates. +1. **Add CSS Entries:** CSS entries from the manifest and additional styles from HTML or `/styles` folder are added to the compilation. +2. **Inject Styles for Content Scripts:** During development, CSS files are dynamically injected into `content_scripts` to benefit from HMR. +3. **Enable HMR for CSS:** HMR is enabled for CSS files across all relevant extension contexts. +4. **Support for Pre-processors:** Files with `.scss`, `.sass`, and `.less` extensions are fully supported and compiled during the build process. +5. **Support for PostCSS:** PostCSS is supported for additional transformations and optimizations on CSS files. + +## CSS Support The following manifest fields are supported for CSS files: -| Manifest Field | File Type Expected | HMR Support | -| ----------------------------- | ------------------------- | ----------- | -| `content_scripts.css` | .css, .scss, .sass, .less | Yes | -| `background.page` | .css, .scss, .sass, .less | Yes | -| `action.default_popup` | .css, .scss, .sass, .less | Yes | -| `chrome_url_overrides.newtab` | .css, .scss, .sass, .less | Yes | -| `options_ui.page` | .css, .scss, .sass, .less | Yes | -| `devtools_page` | .css, .scss, .sass, .less | Yes | +| Manifest Field | File Type Expected | HMR Support | +| --------------------- | ------------------------- | ----------- | +| `content_scripts.css` | .css, .scss, .sass, .less | Yes | ## Sample CSS in `manifest.json` @@ -45,6 +46,8 @@ Here’s a basic example of adding CSS files to `content_scripts` in the `manife CSS can be directly imported in HTML files, with full support for pre-processors like Less and Sass. Simply include the styles with their original extensions, and Extension.js will handle the compilation and injection of these styles: +### Sample HTML File using Sass + ```html @@ -61,6 +64,14 @@ CSS can be directly imported in HTML files, with full support for pre-processors ``` +### Sample script File using Less + +```js +import "./styles/content.less"; + +console.log("Content script loaded"); +``` + ## Output Path The output path for CSS files follows the same logic as scripts or HTML. The CSS will be bundled into `[feature]/index.css` for styles imported in HTML files, based on where it's used. For example, for a `newtab` override, the resulting files would look like this: @@ -80,16 +91,6 @@ content_scripts/ └── index.css ``` -## How Extension.js Handles CSS - -The plugin for CSS file support in Extension.js ensures that the following steps occur during compilation: - -1. **Add CSS Entries:** CSS entries from the manifest and additional styles from HTML or `/styles` folder are added to the compilation. -2. **Inject Styles for Content Scripts:** During development, CSS files are dynamically injected into `content_scripts` to benefit from HMR. -3. **Enable HMR for CSS:** HMR is enabled for CSS files across all relevant extension contexts. -4. **Support for Pre-processors:** Files with `.scss`, `.sass`, and `.less` extensions are fully supported and compiled during the build process. -5. **Support for PostCSS:** PostCSS is supported for additional transformations and optimizations on CSS files. - ## Best Practices - Ensure your manifest fields correctly reference CSS files to take advantage of live-reloading and asset handling. diff --git a/docs/en/docs/development/icons.mdx b/docs/en/docs/development/icons.mdx index 27c87b4..2c7df1b 100644 --- a/docs/en/docs/development/icons.mdx +++ b/docs/en/docs/development/icons.mdx @@ -1,5 +1,4 @@ import { PackageManagerTabs } from "@theme"; - import { AvatarEmoji } from "../../../../theme/components/avatar-emoji"; @@ -8,23 +7,40 @@ import { AvatarEmoji } from "../../../../theme/components/avatar-emoji"; Icons are used in various parts of the extension interface, including the toolbar, context menus, and the extension settings. Extension.js ensures that all icons defined in the `manifest.json` file are correctly processed and emitted to the output directory during the build process. -## Icon File Support +## How Does It Work? + +Extension.js performs the following tasks for icon resources: + +1. **Emit Icon Files:** The icon files referenced in the `manifest.json` are emitted to the output directory of the compilation, ensuring that any updates to the icon files trigger a recompile. +2. **Support for Various Formats:** Extension.js supports multiple image formats, including `.png`, `.jpg`, and `.svg`. +3. **Handle Theme Icons:** Additional icons, like theme icons, are supported and can be included via the manifest or special folders. + +## Icon Support + +The following manifest fields are used to declare icons: + +| Manifest Field | File Type Expected | +| ----------------------------- | --------------------- | +| `action.default_icon` | .png, .jpg, .svg | +| `browser_action.default_icon` | .png, .jpg, .svg | +| `icons` | .png, .jpg, .svg | +| `page_action.default_icon` | .png, .jpg, .svg | +| `sidebar_action.default_icon` | .png, .jpg, .svg (\*) | + +> **Note:** Support for `.svg` is currently partial in some browsers for `sidebar_action.default_icon`. Review browser compatibility before using SVGs in this context. -Extension.js provides comprehensive support for handling icon files. It supports standard image formats such as `.png`, `.jpg`, and `.svg`. All icons referenced in the `manifest.json` are included in the build and served as required by the extension's context. +## Where Icons Appear in Extensions -The following manifest fields use icons: +Icons can appear in different locations across the browser interface, based on where they’re declared in `manifest.json`: -| Manifest Field | File Type Expected | HMR Support | -| ----------------------------- | ------------------ | ----------- | -| `action.default_icon` | .png, .jpg, .svg | Yes | -| `browser_action.default_icon` | .png, .jpg, .svg | Yes | -| `icons` | .png, .jpg, .svg | Yes | -| `page_action.default_icon` | .png, .jpg, .svg | Yes | -| `sidebar_action.default_icon` | .png, .jpg, .svg | Yes | +- **Toolbar Icons:** The `action.default_icon` or `browser_action.default_icon` fields add an icon in the browser's toolbar, making it visible next to the address bar for user interaction. +- **Context Menus:** Declaring icons in `page_action.default_icon` provides a unique icon specific to certain pages, visible only when defined pages are active. +- **Settings and Extensions Menu:** Icons defined under the `icons` field are used in browser settings or the extension management interface. These icons represent the extension and are usually visible within the browser's extension settings page. +- **Side Panel Icons:** The `sidebar_action.default_icon` icon appears within the side panel of supported browsers, such as Firefox, when the extension opens a custom sidebar interface. ## Sample Icon Declaration in `manifest.json` -Here’s a basic example of how to declare icons in your `manifest.json`: +Below is a basic example of how to declare icons in your `manifest.json`: ```json { @@ -42,56 +58,146 @@ Here’s a basic example of how to declare icons in your `manifest.json`: } ``` -This configuration ensures that Extension.js will process and emit the icons to the appropriate location in the output directory during the build process. +## Using Icons in HTML -## Handling Icons +When referencing icons in HTML files, icons will be available in the `dist` folder after building and within a folder based on the feature type. If you want to prevent this behavior, you can use the `public` folder to store icons and other assets. -If you have additional icons that are not directly declared in the `manifest.json`, such as theme icons or extra icons for specific contexts, you can place these icons in the `/public` folder. Extension.js will include these files in the build output as-is, ensuring they are accessible for use throughout your extension. +### Sample HTML File using an icon imported from `public` folder -**Example Usage:** -Place your icons in the `/public/icons` folder: +Assume the following project structure: ```plaintext public/ └── icons/ - ├── icon-16.png ├── icon-48.png - ├── icon-128.png - └── action-icon.png + └── icon-128.png ``` -For more information, refer to the [Special Folders documentation](../features/special-folders.mdx). +Add the following code to your HTML file to reference the icon: + +```html + + + + + + My Extension + + + Extension Icon + + + +``` -## Output Path +### Sample HTML File using an icon imported from any other folder -The output path for icons follows a simple structure based on their context in the manifest. For example, the resulting files would look like this: +Assume the following project structure: + +```plaintext +src/ +├── newtab-page.html +└── icons/ + ├── icon-48.png + └── icon-128.png +``` + +Add the following code to your HTML file to reference the icon: + +```html + + + + + + + My Extension + + + Extension Icon + + + +``` + +The output path for icons will be as follows: ```plaintext dist/ - [browser]/ - ├── icons/ - │ ├── icon-16.png - │ ├── icon-48.png - │ ├── icon-128.png - │ └── action-icon.png - └── other-extension-files + [browser] + └── newtab/ + ├── index.html + └── icon-128.png ``` -## How Extension.js Handles Icons +## Using Icons in JavaScript + +You can import icons in JavaScript files using either the `import` syntax or by referencing the icon path directly via the `chrome.runtime.getURL` method. + +### Sample JavaScript File using an icon imported from + +Assume the following project structure: + +```plaintext +src/ +├── scripts/ +│ └── content.js +└── icons/ + ├── icon-48.png + └── icon-128.png +``` -The plugin responsible for icon handling in Extension.js ensures that the following steps occur during compilation: +Add the following code to your JavaScript file to reference the icon: -1. **Emit Icon Files:** The icon files referenced in the `manifest.json` are emitted to the output directory. -2. **Add to File Dependencies:** Icons are added to the file dependencies of the compilation, ensuring that any updates to the icon files trigger a recompile. -3. **Support for Various Formats:** The plugin supports multiple image formats including `.png`, `.jpg`, and `.svg`. -4. **Handle Theme Icons:** Additional icons like theme icons are also supported, and can be included via the manifest or special folders. +```javascript +// src/scripts/content.js +import icon48 from "../icons/icon-48.png"; + +const img = document.createElement("img"); +img.src = icon48; +document.body.appendChild(img); +``` + +## Output Path + +The output path for icons follows a structure based on their declared manifest fields. After building, icons are located within the `dist/[browser]/` directory, organized as follows: + +```json +{ + "manifest_version": 3, + "name": "My Extension", + "version": "1.0", + "icons": { + "16": "icons/icon-16.png", + "48": "icons/icon-48.png", + "128": "icons/icon-128.png" + }, + "action": { + "default_icon": "action/icon-16.png" + } +} +``` + +```plaintext +dist/ +├── [browser]/ +│ ├── action/ +│ │ └── icon-16.png +│ ├── icons/ +│ │ ├── icon-16.png +│ │ ├── icon-48.png +│ │ ├── icon-128.png +│ │ └── action-icon.png +└── other-extension-files +``` ## Best Practices -- Use the `/public/` folder for additional icons that are not directly declared in the manifest. -- Always declare your icons in the `manifest.json` file to ensure proper inclusion in the build process. -- Ensure that icons are provided in multiple resolutions to support different device pixel ratios (e.g., `16px`, `48px`, `128px`). +- **Organize with `/public/` Folder:** Place additional icons not declared in the manifest within the `/public` folder to keep project structure clear and ensure they’re accessible if needed. +- **Declare Icons in `manifest.json`:** Always declare icons in the manifest file to ensure they’re correctly bundled in the build process. +- **Provide Multiple Resolutions:** Offer icons in multiple resolutions (e.g., `16px`, `48px`, `128px`) to support various device pixel ratios, ensuring icons display clearly on all devices. ## Next Steps -- Learn more about handling icons and other static assets via [Special Folders](../features/special-folders.mdx). +- For handling icons and other assets, learn more about [Special Folders](../features/special-folders.mdx). +- Review Extension.js’s [Documentation on Web-Accessible Resources](../web-accessible-resources) for additional guidance on managing accessible assets. diff --git a/docs/en/docs/development/javascript.mdx b/docs/en/docs/development/javascript.mdx new file mode 100644 index 0000000..5f5d08b --- /dev/null +++ b/docs/en/docs/development/javascript.mdx @@ -0,0 +1,108 @@ +import { PackageManagerTabs } from "@theme"; +import { AvatarImage } from "../../../../theme/components/avatar-image"; + + + +# Scripts + +JavaScript files power multiple aspects of an extension’s functionality. User scripts, background processes, content scripts, and service workers all leverage JavaScript to deliver dynamic behavior and respond to user interactions. Extension.js ensures that JavaScript and TypeScript files defined in the `manifest.json` are correctly processed, with full support for hot-module replacement (HMR) and other development tools. + +## How It Works + +Extension.js handles the following for script resources: + +1. **Emit Script Files:** All JavaScript files are processed and emitted to the `dist` output directory. +2. **Add Script Dependencies:** Script files are included in the file dependencies of the build, so updates trigger recompilation. +3. **Enable HMR for Development:** During development, HMR is enabled for content scripts, background scripts, and user scripts, facilitating fast iteration. +4. **Error Handling:** Missing or misconfigured scripts referenced in `manifest.json` are flagged during the build to prevent runtime issues. + +## Supported Manifest Fields for Scripts + +| Manifest Field | File Type Expected | HMR Support | +| --------------------------- | --------------------------------- | ----------- | +| `background.service_worker` | `.js`, `.ts`, `.mjs`, `.tsx` | No | +| `background.scripts` | `.js`, `.ts`, `.mjs`, `.tsx` | Yes | +| `content_scripts.js` | `.js`, `.ts`, `.mjs`, `.tsx` | Yes | +| `content_scripts.css` | `.css`, `.scss`, `.less`, `.sass` | Yes | +| `user_scripts.api_script` | `.js`, `.ts`, `.mjs`, `.tsx` | Yes | + +## Sample Script Declaration in `manifest.json` + +Here’s an example of defining JavaScript files in `manifest.json`: + +```json +{ + "manifest_version": 3, + "name": "My Extension", + "version": "1.0", + "background": { + "service_worker": "./scripts/background.js" + }, + "content_scripts": [ + { + "matches": [""], + "js": ["./scripts/content-script.js"], + "css": ["./styles/content-style.css"] + } + ] +} +``` + +## Adding and Managing JavaScript + +You should be able to manage y +Extension.js processes additional JavaScript files that provide auxiliary functions, like utilities or helper functions, even if they’re not defined in the manifest. Place these scripts in the `/scripts` folder for automatic inclusion in the build. + +### Example Usage + +Add utility scripts or other JavaScript resources to `/scripts`: + +```plaintext +scripts/ +└── extra-script.js +``` + +## Output Path + +Script output paths are structured according to their context within the manifest: + +```plaintext +# Background scripts: + +background/ +└── scripts.js + +# Service Workers: + +background/ +└── service-worker.js + +# Content Scripts: + +content_scripts/ +└── scripts-0.js + +# User Scripts: + +user_scripts/ +└── api_script.js +``` + +## How Extension.js Handles Scripts + +The plugin for script file support in Extension.js ensures the following during compilation: + +1. **Script Entries:** Entries from both the manifest and the `/scripts` folder are included in the build process. +2. **Inject CSS for Content Scripts:** CSS files within `content_scripts` are dynamically injected to support HMR. +3. **Public Path Fixes:** The public path for content scripts is corrected in production to prevent resource loading issues. +4. **Handle Main World Scripts:** Ensures scripts running in the main world have the correct public path. + +## Best Practices + +- **Utilize the `/scripts` Folder:** Place all utility and helper scripts that aren’t declared in `manifest.json` here. +- **Optimize HMR:** Leverage HMR to quickly iterate on content and background scripts during development. +- **Modularize Code:** Organize scripts by functionality to improve maintainability and readability of your extension’s codebase. + +## Next Steps + +- Learn how to structure and manage scripts using [Special Folders](../features/special-folders.mdx). diff --git a/docs/en/docs/development/json.mdx b/docs/en/docs/development/json.mdx index 12ad854..0bfe28a 100644 --- a/docs/en/docs/development/json.mdx +++ b/docs/en/docs/development/json.mdx @@ -7,14 +7,22 @@ import { AvatarImage } from "../../../../theme/components/avatar-image"; JSON in browser extensions provide data for rulesets, managed storage schemas, and more. Extension.js handles the inclusion, bundling, and processing of JSON files referenced in the `manifest.json`, ensuring they are correctly emitted and added to the compilation output. -## JSON File Support +## How Does It Work? -Extension.js supports handling JSON files defined in the `manifest.json`, ensuring that they are processed and output correctly. This includes rulesets for declarative network requests and storage-managed schemas. The following manifest fields are supported: +Extension.js performs the following tasks for JSON resources: -| Manifest Field | File Type Expected | HMR Support | -| ---------------------------------------- | ------------------ | ----------- | -| `declarative_net_request.rule_resources` | .json | Yes | -| `storage.managed_schema` | .json | Yes | +1. **Emit JSON Files:** The JSON files referenced in the `manifest.json` are emitted to the output directory. +2. **Add to File Dependencies:** JSON files are added to the file dependencies of the compilation, ensuring that any updates to the JSON files trigger a recompile. +3. **Error Handling:** If a referenced JSON file is missing or incorrectly configured, warnings are generated to help developers fix issues during the build process. + +## JSON Support + +The following manifest fields are used to declare JSON files: + +| Manifest Field | File Type Expected | +| ---------------------------------------- | ------------------ | +| `declarative_net_request.rule_resources` | .json | +| `storage.managed_schema` | .json | ## Sample JSON Declaration in `manifest.json` @@ -42,22 +50,6 @@ Here’s an example of how to declare a JSON file in your `manifest.json`: This configuration ensures that Extension.js will process the JSON files and include them in the final output of your extension. -## Handling JSON Files - -If you have additional JSON files that are not directly declared in the `manifest.json`, such as extra configuration or data files, you can place these JSON files in the `/public` folder. Extension.js will include these files in the build output as-is, ensuring they are accessible for use throughout your extension. - -**Example Usage:** -Place your JSON files in the `/public/json` folder: - -```plaintext -public/ -└── json/ - ├── ruleset.json - └── storage-schema.json -``` - -For more information, refer to the [Special Folders documentation](../features/special-folders.mdx). - ## Output Path The output path for JSON files follows a simple structure based on their context in the manifest. For example, the resulting files would look like this: @@ -72,15 +64,6 @@ dist/ └── other-extension-files ``` -## How Extension.js Handles JSON - -The plugin responsible for handling JSON files in Extension.js ensures that the following steps occur during compilation: - -1. **Emit JSON Files:** The JSON files referenced in the `manifest.json` are emitted to the output directory. -2. **Add to File Dependencies:** JSON files are added to the file dependencies of the compilation, ensuring that any updates to the JSON files trigger a recompile. -3. **Support for Multiple Features:** JSON handling supports declarative network requests, managed storage schemas, and other JSON-based manifest fields. -4. **Error Handling:** If a referenced JSON file is missing or incorrectly configured, warnings are generated to help developers fix issues during the build process. - ## Best Practices - Use the `/public/` folder for additional JSON files that are not directly declared in the manifest. diff --git a/docs/en/docs/development/locales.mdx b/docs/en/docs/development/locales.mdx index a7b5bc2..7ca10ee 100644 --- a/docs/en/docs/development/locales.mdx +++ b/docs/en/docs/development/locales.mdx @@ -7,14 +7,23 @@ import { AvatarImage } from "../../../../theme/components/avatar-image"; Locales allow browser extensions to support multiple languages and enhancing the user experience. Extension.js handles locales defined in your `manifest.json` as the browser would, and ensures that they are emitted and included in the output directory, making them accessible during runtime. +## How Does It Work? + +Extension.js performs the following tasks for locale files in Extension.js: + +1. **Emit Locale Files:** Locale files declared in the `manifest.json` are emitted to the output directory. +2. **Add to File Dependencies:** Locale files are added to the file dependencies of the compilation, ensuring any updates trigger a rebuild. +3. **Support for Multiple Languages:** Support for multiple languages through the `_locales` folder is provided. +4. **Error Handling:** Warnings are generated if locale files are missing or incorrectly configured during the build process. + ## Locales File Support Extension.js offers robust support for locales, ensuring that all defined translations are correctly emitted and watched for changes. The following manifest fields are used for declaring locales: -| Manifest Field | File Type Expected | HMR Support | +| Manifest Field | File Type Expected | Reload | | ----------------- | ------------------ | ----------- | -| `default_locale` | .json | Yes | -| `_locales/*.json` | .json | Yes | +| `default_locale` | .json | Live-reload | +| `_locales/*.json` | .json | Live-reload | ## Sample Locales Declaration in `manifest.json` @@ -66,15 +75,6 @@ dist/ └── messages.json ``` -## How Extension.js Handles Locales - -The plugin responsible for handling locale files in Extension.js ensures the following steps occur during compilation: - -1. **Emit Locale Files:** Locale files declared in the `manifest.json` are emitted to the output directory. -2. **Add to File Dependencies:** Locale files are added to the file dependencies of the compilation, ensuring any updates trigger a rebuild. -3. **Support for Multiple Languages:** Support for multiple languages through the `_locales` folder is provided. -4. **Error Handling:** Warnings are generated if locale files are missing or incorrectly configured during the build process. - ## Best Practices - Use the `_locales` folder to organize translations for different languages. diff --git a/docs/en/docs/development/scripts.mdx b/docs/en/docs/development/scripts.mdx deleted file mode 100644 index 5dbf7ae..0000000 --- a/docs/en/docs/development/scripts.mdx +++ /dev/null @@ -1,104 +0,0 @@ -import { PackageManagerTabs } from "@theme"; -import { AvatarImage } from "../../../../theme/components/avatar-image"; - - - -# Scripts - -In an extension, JavaScript files empower background processes, content scripts, user scripts, and service workers. Extension.js ensures that JavaScript and TypeScript files defined in the `manifest.json` are correctly processed, with full support for hot-module replacement (HMR) and other development tools. - -## Script File Support - -Extension.js offers comprehensive support for script files, ensuring HMR where applicable. It handles entry point injection for JavaScript, TypeScript, and CSS in content scripts, service workers, and background scripts. - -The following manifest fields are supported for JavaScript and related files: - -| Manifest Field | File Type Expected | HMR Support | -| --------------------------- | ------------------------- | ----------- | -| `background.service_worker` | .js, .ts, .mjs, .tsx | No | -| `background.scripts` | .js, .ts, .mjs, .tsx | Yes | -| `content_scripts.js` | .js, .ts, .mjs, .tsx | Yes | -| `content_scripts.css` | .css, .scss, .less, .sass | Yes | -| `user_scripts.api_script` | .js, .ts, .mjs, .tsx | Yes | - -## Sample Script Files - -Here’s a basic example of defining scripts in the `manifest.json`: - -```json -{ - "manifest_version": 3, - "name": "My Extension", - "version": "1.0", - "background": { - "service_worker": "./scripts/background.js" - }, - "content_scripts": [ - { - "matches": [""], - "js": ["./scripts/content-script.js"], - "css": ["./styles/content-style.css"] - } - ] -} -``` - -## Handling Additional Scripts - -For scripts that are not declared in `manifest.json`, such as utility scripts or other JavaScript files that provide additional functionality, place them in the `/scripts` folder. This folder is automatically processed by Extension.js to ensure all scripts are included in the build. - -**Example Usage:** -Add your additional script files to the `/scripts` folder: - -```plaintext -scripts/ -└── extra-script.js -``` - -For more information on organizing these files, refer to the [Special Folders documentation](../features/special-folders.mdx). - -## Output Path - -The output path for scripts is the following: - -```plaintext -# background scripts: - -background/ -└── scripts.js - -# service workers: - -background/ -└── service-worker.js - -# content scripts: - -content_scripts/ -└── scripts-0.js - -# user scripts: - -user_scripts/ -└── api_script.js -``` - -## How Extension.js Handles Scripts - -The plugin for script file support in Extension.js ensures the following steps occur during compilation: - -1. **Add Script Entries:** Script entries from the manifest and additional scripts from the `/scripts` folder are added to the compilation process. -2. **Inject CSS for Content Scripts:** During development, CSS files in `content_scripts` are injected dynamically for HMR support. -3. **Enable HMR for Scripts:** HMR is enabled for content scripts, background scripts, and user scripts during development. -4. **Fix Public Path in Production:** Fixes issues with content scripts not finding the correct public path in the production build. -5. **Handle Public Path for Main World Scripts:** Ensures correct public path for scripts running in the main world, such as content scripts. - -## Best Practices - -- Use the `/scripts` folder for additional JavaScript files that are not defined in `manifest.json`. -- Ensure your manifest fields correctly reference script files for proper HMR and asset injection. -- Keep your scripts organized and modular to improve maintainability and scalability of your extension. - -## Next Steps - -- Learn how to structure and work with [Special Folders](../features/special-folders.mdx) for handling script files outside of the manifest. diff --git a/docs/en/docs/development/web_accessible_resources.mdx b/docs/en/docs/development/web_accessible_resources.mdx index 55e37b7..3d90449 100644 --- a/docs/en/docs/development/web_accessible_resources.mdx +++ b/docs/en/docs/development/web_accessible_resources.mdx @@ -1,99 +1,182 @@ -import { PackageManagerTabs } from "@theme"; import { AvatarImage } from "../../../../theme/components/avatar-image"; -# Web Accessible Resources +# Extension Config File (`extension.config.js`) -Web-accessible resources are files within an extension that can be accessed by web pages or other extensions. These resources are often used for images, scripts, or stylesheets that are required by content scripts or pages embedded within an extension's context. +> **Warning**: This feature is a work in progress and may be incomplete or subject to change. +> If you see an error or something that could be improved, please make a pull-request. +> The link that documents this feature can be found at the bottom of the page. -Extension.js ensures proper handling of `web_accessible_resources` paths in your `manifest.json`, including assets imported in content scripts. This feature allows you to expose certain files from your extension to external web pages or make them available for other parts of the extension. +The `extension.config.js` file enables developers to adjust the behavior of Extension.js. +This configuration file provides flexibility by enabling browser-specific configurations, +command customization, and support for the massive ecosystem of webpack loaders and plugins. -## Web Accessible Resources Support +## How Does It Work? -The following manifest field is used to declare web-accessible resources: +Adding a `extension.config.js` file at the same level as your `manifest.json` file will +extend the capabilities of Extension.js. The config file includes the following keys: -| Manifest Field | File Type Expected | HMR Support | -| -------------------------- | ------------------ | ----------- | -| `web_accessible_resources` | Any file type | Yes | +| Key | Description | +| ---------- | --------------------------------------------------------- | +| `browser` | Defines browser-specific configurations. | +| `commands` | Customizes command behavior (`dev`, `preview`, `build`). | +| `config` | Modifies the webpack configuration for added flexibility. | -## Sample `manifest.json` File +### Browser Configuration -Here's an example of how to declare web-accessible resources in the `manifest.json` file: +The `browser` key allows setting up browser-specific preferences, profiles, binaries, +and flags. Below is an example configuration for Chrome and Firefox: -```json -{ - "manifest_version": 3, - "name": "My Extension", - "version": "1.0", - "web_accessible_resources": [ - { - "resources": ["images/*.png", "scripts/*.js", "styles/*.css"], - "matches": [""] - } - ], - "content_scripts": [ - { - "matches": ["https://example.com/*"], - "css": ["styles/content.css"], - "js": ["scripts/content.js"] - } - ] +```js +browser: { + chrome: { + profile: 'path/to/profile', + preferences: { darkMode: true }, + browserFlags: ['--disable-web-security'], + chromeBinary: 'path/to/custom/chrome', + }, + firefox: { + geckoBinary: 'path/to/custom/firefox', + } } ``` -In this example, the `web_accessible_resources` field exposes specific resources (images, scripts, styles) for web pages that match the pattern defined in `matches`. - -## Handling Web-Accessible Resources Not Declared in `manifest.json` - -If you need to include additional files as web-accessible resources but prefer not to declare them directly in the `manifest.json`, you can place these files in the `/public` folder. Extension.js will automatically process and make them accessible without needing to modify the manifest. - -**Example Usage:** -Place your web-accessible files in the `/public` folder for automatic handling: - -```plaintext -public/ -└── assets/ - ├── images/ - │ └── logo.png - ├── scripts/ - │ └── external.js - └── styles/ - └── global.css +| Property | Description | Example | +| -------------- | ------------------------------------------ | ---------------------------- | +| `profile` | Specifies the path to the browser profile. | `'path/to/profile'` | +| `preferences` | Customizes preferences such as dark mode. | `{ darkMode: true }` | +| `browserFlags` | Adds flags to the browser launch process. | `['--disable-web-security']` | +| `chromeBinary` | Sets a custom Chrome binary path. | `'path/to/custom/chrome'` | +| `geckoBinary` | Sets a custom Firefox binary path. | `'path/to/custom/firefox'` | + +> **Additional Resources**: +> +> - For a list of available flags for Chrome, refer to the [Chrome Command Line Switches](https://peter.sh/experiments/chromium-command-line-switches/). +> - For Edge flags, visit the [Microsoft Edge Command Line Options](https://learn.microsoft.com/en-us/deployedge/microsoft-edge-command-line-options). +> - For Firefox, check the [Firefox Developer Documentation](https://developer.mozilla.org/en-US/docs/Mozilla/Command_Line_Options). + +### Commands Configuration + +Use the `commands` key to customize how Extension.js runs commands like `dev`, `preview`, +and `build`. Here's an example: + +```js +commands: { + dev: { + browser: 'chrome', + polyfill: true, + }, + build: { + zipFilename: 'my-extension.zip', + zip: true, + zipSource: true, + } +} ``` -For more information, refer to the [Special Folders documentation](../features/special-folders.mdx). - -## Output Path - -The output path for web-accessible resources will follow the structure defined in your manifest or the `/public` folder. The resulting files will look like this: +| Property | Description | Example | +| ------------- | ------------------------------------------------------- | -------------------- | +| `browser` | Specifies the browser for dev or preview mode. | `'chrome'` | +| `polyfill` | Enables polyfills for legacy browser compatibility. | `true` | +| `zipFilename` | Sets the filename for the output zip file during build. | `'my-extension.zip'` | +| `zip` | Enables zipping the extension in build process. | `true` | +| `zipSource` | Includes the source code in the zip file. | `true` | + +### Webpack Configuration + +The `config` key allows you to modify the default webpack configuration. This gives you +the power to add additional loaders or plugins: + +```js +config: (config) => { + config.module.rules.push({ + test: /\.mdx$/, + use: ["babel-loader", "@mdx-js/loader"], + }); + return config; +}; +``` -```plaintext -dist/ -└── images/ - └── logo.png -└── scripts/ - └── external.js -└── styles/ - └── global.css +## Full Sample `extension.config.js` + +Below are sample configurations for the different sections in `extension.config.js`. + +### Browser Configuration Sample + +```js +module.exports = { + browser: { + chrome: { + profile: "path/to/chrome/profile", + preferences: { theme: "dark" }, + browserFlags: ["--disable-extensions"], + chromeBinary: "path/to/custom/chrome", + }, + firefox: { + profile: "path/to/firefox/profile", + preferences: { darkMode: true }, + geckoBinary: "path/to/custom/firefox", + }, + }, +}; ``` -## How Extension.js Handles Web Accessible Resources +### Commands Configuration Sample + +```js +module.exports = { + commands: { + dev: { + browser: "chrome", + profile: "path/to/chrome/profile", + polyfill: true, + port: 8080, + noOpen: false, + }, + preview: { + browser: "firefox", + profile: "path/to/firefox/profile", + }, + build: { + zipFilename: "extension.zip", + zip: true, + zipSource: true, + silent: true, + }, + }, +}; +``` -The plugin responsible for handling web-accessible resources in Extension.js performs the following tasks: +### Webpack Configuration Sample + +```js +const NodePolyfillPlugin = require("node-polyfill-webpack-plugin"); + +module.exports = { + config: (config) => { + config.plugins = [ + ...config.plugins, + new NodePolyfillPlugin({ + additionalAliases: ["process"], + }), + ]; + return config; + }, +}; +``` -1. **Generate Manifest Patches:** It updates the `manifest.json` file with paths for web-accessible resources based on the content scripts and assets being used. -2. **Add Resources to Compilation:** Assets used in content scripts or referenced in the manifest are added to the compilation process. -3. **Emit Assets:** All assets declared as web-accessible are emitted to the output directory. -4. **Support for Multiple Asset Types:** The plugin supports various file types including images, scripts, and stylesheets. -5. **Error Handling:** It checks for missing assets and issues warnings if resources declared in the manifest are not found during the build process. +The `extension.config.js` types [are defined here](https://github.com/extension-js/extension.js/blob/main/programs/develop/commands/commands-lib/config-types.ts). ## Best Practices -- Always declare resources in `web_accessible_resources` if they are intended to be accessible by web pages or other external scripts. -- Place additional resources that need to be web-accessible in the `/public` folder to keep your `manifest.json` clean and organized. -- Ensure your content scripts correctly reference these assets, especially when working with external web pages. +- **Use the `extension.config.js` file**: Leverage the `extension.config.js` file to + customize your extension's behavior. +- **Separate browser-specific configurations**: Keep browser-specific configurations + in the `browser` key. +- **Customize commands**: Use the `commands` key to adjust the behavior of commands + like `dev`, `preview`, and `build`. ## Next Steps -- Learn more about managing assets and resources with [Special Folders](../features/special-folders.mdx). +- Learn more about the [Browsers Available](#). diff --git a/docs/en/docs/features/_meta.json b/docs/en/docs/features/_meta.json index 2e628c1..9201031 100644 --- a/docs/en/docs/features/_meta.json +++ b/docs/en/docs/features/_meta.json @@ -3,7 +3,7 @@ { "name": "browser-fields", "label": "Browser-Specific Manifest Fields" }, { "name": "special-folders", "label": "Special Folders" }, { "name": "environment-variables", "label": "Environment Variables" }, - { "name": "config", "label": "Extended Configuration File" }, + { "name": "config", "label": "extension.config.js" }, { "name": "reload-and-hmr", "label": "Reload and Hot-Module Replacement" }, { "name": "path-resolution", "label": "Predictable Path Resolution" }, { "name": "packaging", "label": "Production-Ready Builds" } diff --git a/docs/en/docs/features/config.mdx b/docs/en/docs/features/config.mdx index 1f605da..7de80fe 100644 --- a/docs/en/docs/features/config.mdx +++ b/docs/en/docs/features/config.mdx @@ -4,21 +4,29 @@ import { AvatarImage } from "../../../../theme/components/avatar-image"; # Extension Config File (`extension.config.js`) -> **Warning**: This feature is a work in progress and may be incomplete or subject to change. If you see an error or something that could be improved, please make a pull-request. The link that documents this feature can be found at the bottom of the page. +> **Warning**: This feature is a work in progress and may be incomplete or subject to change. +> If you see an error or something that could be improved, please make a pull-request. +> The link that documents this feature can be found at the bottom of the page. -The `extension.config.js` file enables developers to adjust the behavior of Extension.js. This configuration file provides flexibility by enabling browser-specific configurations, command customization, and support for the massive ecosystem of webpack loaders and plugins. +The `extension.config.js` file enables developers to adjust the behavior of Extension.js. +This configuration file provides flexibility by enabling browser-specific configurations, +command customization, and support for the massive ecosystem of webpack loaders and plugins. ## How Does It Work? -The `extension.config.js` file includes the following keys: +Adding a `extension.config.js` file at the same level as your `manifest.json` file will +extend the capabilities of Extension.js. The config file includes the following keys: -- **`browser`**: Defines browser-specific configurations. -- **`commands`**: Customizes the behavior of commands (`dev`, `preview`, `build`). -- **`config`**: Modifies the webpack configuration for further flexibility. +| Key | Description | +| ---------- | --------------------------------------------------------- | +| `browser` | Defines browser-specific configurations. | +| `commands` | Customizes command behavior (`dev`, `preview`, `build`). | +| `config` | Modifies the webpack configuration for added flexibility. | ### Browser Configuration -The `browser` key allows setting up browser-specific preferences, profiles, binaries, and flags. Below is an example configuration for Chrome and Firefox: +The `browser` key allows setting up browser-specific preferences, profiles, binaries, +and flags. Below is an example configuration for Chrome and Firefox: ```js browser: { @@ -34,15 +42,18 @@ browser: { } ``` -- **profile:** Specifies the path to the browser profile. -- **preferences:** Customizes preferences such as dark mode. -- **browserFlags:** Adds flags to the browser launch process. -- **chromeBinary:** Sets a custom Chrome binary. -- **geckoBinary:** Sets a custom Firefox binary. +| Property | Description | Example | +| -------------- | ------------------------------------------ | ---------------------------- | +| `profile` | Specifies the path to the browser profile. | `'path/to/profile'` | +| `preferences` | Customizes preferences such as dark mode. | `{ darkMode: true }` | +| `browserFlags` | Adds flags to the browser launch process. | `['--disable-web-security']` | +| `chromeBinary` | Sets a custom Chrome binary path. | `'path/to/custom/chrome'` | +| `geckoBinary` | Sets a custom Firefox binary path. | `'path/to/custom/firefox'` | ### Commands Configuration -Use the commands key to customize how Extension.js runs commands like dev, preview, and build. Here's an example: +Use the `commands` key to customize how Extension.js runs commands like `dev`, `preview`, +and `build`. Here's an example: ```js commands: { @@ -58,15 +69,18 @@ commands: { } ``` -- **browser:** Specifies the browser to use during dev or preview mode. -- **polyfill:** Enables polyfills for legacy browser compatibility. -- **zipFilename:** Sets the filename for the output zip file during the build process. -- **zip:** Enables zipping the extension during the build process. -- **zipSource:** Includes the source code in the zip file. +| Property | Description | Example | +| ------------- | ------------------------------------------------------- | -------------------- | +| `browser` | Specifies the browser for dev or preview mode. | `'chrome'` | +| `polyfill` | Enables polyfills for legacy browser compatibility. | `true` | +| `zipFilename` | Sets the filename for the output zip file during build. | `'my-extension.zip'` | +| `zip` | Enables zipping the extension in build process. | `true` | +| `zipSource` | Includes the source code in the zip file. | `true` | ### Webpack Configuration -The config key allows you to modify the default webpack configuration. This gives you the power to add additional loaders or plugins: +The `config` key allows you to modify the default webpack configuration. This gives you +the power to add additional loaders or plugins: ```js config: (config) => { @@ -78,61 +92,84 @@ config: (config) => { }; ``` -This example adds MDX support by modifying webpack's module rules. +## Full Sample `extension.config.js` -## Example extension.config.js +Below are sample configurations for the different sections in `extension.config.js`. -Here is a sample `extension.config.js` file that combines browser, command, and webpack customization: +### Browser Configuration Sample ```js -const NodePolyfillPlugin = require('node-polyfill-webpack-plugin') - -/** @type {import('extension').FileConfig} */ module.exports = { browser: { chrome: { profile: "path/to/chrome/profile", preferences: { theme: "dark" }, browserFlags: ["--disable-extensions"], + chromeBinary: "path/to/custom/chrome", }, firefox: { + profile: "path/to/firefox/profile", + preferences: { darkMode: true }, geckoBinary: "path/to/custom/firefox", }, }, +}; +``` + +### Commands Configuration Sample + +```js +module.exports = { commands: { dev: { - browser: "firefox", - profile: "path/to/firefox/profile", + browser: "chrome", + profile: "path/to/chrome/profile", polyfill: true, + port: 8080, + noOpen: false, }, preview: { - browser: "chrome", + browser: "firefox", + profile: "path/to/firefox/profile", }, build: { zipFilename: "extension.zip", zip: true, + zipSource: true, + silent: true, }, }, +}; +``` + +### Webpack Configuration Sample + +```js +const NodePolyfillPlugin = require("node-polyfill-webpack-plugin"); + +module.exports = { config: (config) => { config.plugins = [ ...config.plugins, new NodePolyfillPlugin({ - additionalAliases: ['process'] - }) - ] - - return config - } -} - + additionalAliases: ["process"], + }), + ]; + return config; + }, }; ``` +The `extension.config.js` types [are defined here](https://github.com/extension-js/extension.js/blob/main/programs/develop/commands/commands-lib/config-types.ts). + ## Best Practices -- **Use the `extension.config.js` file**: Leverage the `extension.config.js` file to customize your extension's behavior. -- **Separate browser-specific configurations**: Keep browser-specific configurations in the `browser` key. -- **Customize commands**: Use the `commands` key to adjust the behavior of commands like `dev`, `preview`, and `build`. +- **Use the `extension.config.js` file**: Leverage the `extension.config.js` file to + customize your extension's behavior. +- **Separate browser-specific configurations**: Keep browser-specific configurations + in the `browser` key. +- **Customize commands**: Use the `commands` key to adjust the behavior of commands + like `dev`, `preview`, and `build`. ## Next Steps