diff --git a/package.json b/package.json index 7c2d41f6e..cd2cfa3bf 100644 --- a/package.json +++ b/package.json @@ -12,9 +12,9 @@ "last 2 Firefox versions" ], "scripts": { - "build": "rm -rf _site dist; eleventy; parcel build src/home/index.html '_site/*.html' _site/*/index.html '_site/*/*/*.html' --public-url $(node public-url.js)", + "build": "rm -rf _site dist; eleventy; parcel build src/home/index.html '_site/*.html' '_site/*/index.html' '_site/*/*/*.html' --public-url $(node public-url.js)", "watch": "eleventy --watch", - "serve": "parcel src/home/index.html '_site/*.html' _site/*/index.html '_site/*/*/*.html'", + "serve": "parcel src/home/index.html '_site/*.html' '_site/*/index.html' '_site/*/*/*.html'", "start": "run-p watch serve", "debug": "DEBUG=* eleventy", "lint": "prettier --write 'generate-api-docs/*.js' 'src/**/*.{js,json,md,scss}'", diff --git a/src/recipes/web-extension.md b/src/recipes/web-extension.md index 9001f0411..8faeeef60 100644 --- a/src/recipes/web-extension.md +++ b/src/recipes/web-extension.md @@ -17,8 +17,7 @@ First, install `@parcel/config-webextension` into your project: yarn add @parcel/config-webextension --dev ``` -Next, you'll need a [manifest.json](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json) file, which will be the entry point of your extension. See [this guide](https://developer.chrome.com/docs/extensions/mv3/getstarted/) for details on how to set it up. Both Manifest V2 and V3 are supported. You can use [TypeScript](), [Vue](), and any other languages supported by Parcel within your web extension code. - +Next, you'll need a [manifest.json](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json) file, which will be the entry point of your extension. See [this guide](https://developer.chrome.com/docs/extensions/mv3/getstarted/) for details on how to set it up. Both Manifest V2 and V3 are supported. You can use [TypeScript](/languages/typescript), [Vue](/languages/vue), and any other languages supported by Parcel within your web extension code. {% sample %} {% samplefile "manifest.json" %} @@ -32,10 +31,12 @@ Next, you'll need a [manifest.json](https://developer.mozilla.org/en-US/docs/Moz "service_worker": "background.ts", "type": "module" }, - "content_scripts": [{ - "matches": ["*://github.com/parcel-bundler/*"], - "js": ["parcel-content-script.ts"] - }] + "content_scripts": [ + { + "matches": ["*://github.com/parcel-bundler/*"], + "js": ["parcel-content-script.ts"] + } + ] } ``` @@ -48,6 +49,12 @@ To build your extension, run Parcel using your `manifest.json` as an entry, and parcel build manifest.json --config @parcel/config-webextension ``` +{% warning %} + +With the default Web Extension config, the manifest has to be called `manifest.json` (and cannot be just any file with a `json` extension). + +{% endwarning %} + You can also create a `.parcelrc` file in your project extending `@parcel/config-webextension`. This way you don't need to pass the `--config` option to the Parcel CLI every time. {% sample %} @@ -62,6 +69,26 @@ You can also create a `.parcelrc` file in your project extending `@parcel/config {% endsamplefile %} {% endsample %} +To make Parcel treat some other file as a manifest apart from `manifest.json`, add a few more lines to the `.parcelrc`: + +{% sample %} +{% samplefile ".parcelrc" %} + +```json +{ + "extends": "@parcel/config-webextension", + "transformers": { + "some-other-manifest.json": ["@parcel/transformer-webextension"] + }, + "packagers": { + "some-other-manifest.json": "@parcel/packager-webextension" + } +} +``` + +{% endsamplefile %} +{% endsample %} + ## HMR Due to [restrictions on Content Security Policy](https://developer.chrome.com/docs/extensions/mv3/intro/mv3-migration/#content-security-policy) in MV3, HMR is not supported, but updating your code will cause the extension to reload. For MV2, HMR is fully supported by default. Reloading pages with content scripts will reload the extension in both versions. @@ -97,7 +124,7 @@ In development mode, your background scripts will receive a message event with t ### Styling -Any styles imported in a content script will be injected into the `css` property of that content script and will thus apply to the entire page. Usually this is what you want, but if not you can always use [CSS modules]() to prevent the styles from applying to the original site. +Any styles imported in a content script will be injected into the `css` property of that content script and will thus apply to the entire page. Usually this is what you want, but if not you can always use [CSS modules](/languages/css#css-modules) to prevent the styles from applying to the original site. Additionally, content script CSS resolves links to the site they are injected into, so you won't be able to reference local assets. You should [inline your bundles]() to resolve this issue. @@ -123,16 +150,16 @@ Additionally, content script CSS resolves links to the site they are injected in Lastly, hot reload may not work when adding or removing CSS linked from inside an `import()` in content scripts, while synchronous `import` has no such issues. This is a known limitation and will be fixed in a future version. ### `web_accessible_resources` -Any resources you use in a content script will automatically be added into `web_accessible_resources`, so you don't usually need to specify anything in `web_accessible_resources` at all. For example, the following content script will work without issues: +Any resources you use in a content script will automatically be added into `web_accessible_resources`, so you don't usually need to specify anything in `web_accessible_resources` at all. For example, the following content script will work without issues: {% sample %} {% samplefile "content-script.js" %} ```js -import myImage from 'url:./image.png'; +import myImage from "url:./image.png"; -const injectedImage = document.createElement('img'); +const injectedImage = document.createElement("img"); injectedImage.src = myImage; document.body.appendChild(injectedImage); ``` diff --git a/yarn.lock b/yarn.lock index 21c0152b8..055848484 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1966,9 +1966,9 @@ __metadata: linkType: hard "caniuse-lite@npm:^1.0.30001400": - version: 1.0.30001486 - resolution: "caniuse-lite@npm:1.0.30001486" - checksum: 5e8c2ba2679e4ad17dea6d2761a6449b814441bfeac81af6cc9d58af187df6af4b79b27befcbfc4a557e720b21c0399a7d1911c8705922e38938dcc0f40b5d4b + version: 1.0.30001547 + resolution: "caniuse-lite@npm:1.0.30001547" + checksum: ec0fc2b46721887f6f4aca1f3902f03d9a1a07416d16a86b7cd4bfba60e7b6b03ab3969659d3ea0158cc2f298972c80215c06c9457eb15c649d7780e8f5e91a7 languageName: node linkType: hard