使用 Percel 构建 Chrome 扩展

Percel 有丰富的开箱即用的功能，例如 TypeScript 、 CoffeeScript 、 Vue 、 React 、 Sass 、 Stylus 、 Less 等等。我们几乎不需要任何配置就可以使用它来开发 Chrome 扩展。以下内容记录了我使用 Percel 构建一个 Chrome 扩展来覆盖 Chrome 浏览器的新标签页面的过程。

创建项目文件夹

首先创建 newtab 文件夹作为项目根目录：

$ mkdir newtab
$ cd newtab

安装项目依赖

使用 pnpm 安装项目依赖，你可以把以下命令替换成你喜欢的 Node.js 包管理工具的等价命令。

$ pnpm add -D parcel @parcel/config-webextension process

虽然我们没有创建 newtab/package.json 文件，但是上面的命令自动为我们创建了这个文件：

{
  "devDependencies": {
    "@parcel/config-webextension": "^2.8.3",
    "parcel": "^2.8.3",
    "process": "^0.11.10"
  }
}

创建 manifest.json

在 newtab 项目文件夹中创建 src 文件夹，然后在 src 文件夹中创建 newtab/src/manifest.json 文件，这个 JSON 文件至少要包含 manifest_version 、 name 、 version 等三个属性。

{
  "manifest_version": 3,
  "name": "New Tab",
  "version": "1.0"
}

运行构建

尝试使用以下命令构建扩展，这会生成 newtab/dist/manifest.json 文件。稍后我们会将下面的脚本添加到 newtab/package.json 文件的 scripts 字段中。

$ npx parcel build manifest.json --config @parcel/config-webextension

我们也可以创建 newtab/.parcelrc 文件，这样上面那条命令就不再需要传递 --config 参数了。

{
  "extends": "@parcel/config-webextension"
}

运行开发服务器

在终端中运行以下命令即可运行开发服务器：

$ npx parcel watch src/manifest.json --host localhost

然后在 Chrome 浏览器新标签页输入 chrome://extensions/ 后回车，打开扩展程序页面。点击开发者模式开关，启用开发者模式。点击加载已解压的扩展程序按钮选择 newtab/dist 文件夹即可加载开发中的扩展。注意修改代码会导致扩展重新加载，但因为 Manifest V3 内容安全策略的限制，这并不是我们以为的热重载。

NPM scripts

为了方便日常开发，将构建扩展和运行开发服务器的命令添加到 newtab/package.json 文件的 scripts 属性中：

{
  "scripts": {
    "start": "parcel watch src/manifest.json --host localhost",
    "build": "parcel build src/manifest.json"
  }
  // 这里省略了原有一部分内容 ...
}

注意，如果你没有创建 newtab/.parcelrc 文件，要在这两条命令后面添加 --config @parcel/config-webextension 。

新标签页 HTML

创建要在 Chrome 新标签页中显示的 HTML 页面 newtab/src/newtab.html 。这里只简单表示下，真实的项目肯定非常复杂的：

<html>
  <body>
    <div>我的新标签页</div>
  </body>
</html>

修改 newtab/src/manifest.json ，添加以下内容：

{
  // 这里省略了原有一部分内容 ...
  "chrome_url_overrides": {
    "newtab": "newtab.html"
  }
}

现在可以在 Chrome 浏览器中打开一个新的标签页，可以看到 Chrome 的提示说新标签已被修改。如果没有提示，你可能需要到扩展程序页面重新加载扩展。

安装并使用 React

TypeScript 是 100% 开箱即用的。我们安装 react 的包和相应的类型定义文件后，就能直接使用 React 和 TypeScript 开发 Chrome 扩展了：

$ pnpm add react react-dom
$ pnpm add -D @types/react @types/react-dom

创建 newtab/src/newtab.tsx 文件，添加以下内容：

import React from "react";
import ReactDOM from "react-dom/client";

ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
  <div>我的新标签页之 React 版</div>
);

将 newtab/src/newtab.html 的内容替换为：

<!DOCTYPE html>
<html lang="zh-Hans-CN">
  <!-- 省略了 head 标签部分 -->
  <body>
    <div id="root"></div>
    <script type="module" src="newtab.tsx"></script>
  </body>
</html>

接下来

您可以参考 Percel 官方文档和 Chrome 扩展开发文档了解更多信息。