addons frontend

插件前端

前端基礎設施和程式碼來補充 mozilla/addons-server。

安全錯誤報告

該程式碼及其相關的生產網站包含在 Mozilla 的網路和服務錯誤賞金計畫中。如果您發現安全漏洞，請透過排程和常見問題頁面中概述的流程提交。有關此應用程式的更多技術詳細資訊可從 Bug Bounty Onramp 頁面取得。

請使用網路安全錯誤表單透過 Bugzilla 提交所有與安全相關的錯誤。

切勿透過 Github Issue 或電子郵件提交與安全相關的錯誤。

要求

• 您需要 Node LTS（長期支援）版本。
• 安裝yarn來管理依賴關係並執行腳本。

在開發中管理多個節點版本的最簡單方法是使用 nvm。

開始使用

如果您使用的是 Windows，請確保也遵循 Windows 指南。

• 輸入yarn來安裝所有依賴項
• 輸入yarn amo:stage啟動連接到託管登台伺服器的本機伺服器

開發命令

以下是您可以運行的一些命令：

命令	描述
紗線阿莫：奧林匹亞	使用本機插件伺服器環境中的資料啟動開發伺服器/代理程式（適用於 amo）。
紗線阿莫：開發	使用來自開發伺服器的資料啟動開發伺服器/代理程式（對於 amo）（https://addons-dev.allizom.org/）
紗線 amo:dev-https	與amo:dev相同，但使用 HTTPS，可從以下網址取得：https://example.com:3000/。閱讀有關設置此環境的信息
紗線阿莫：舞台	使用來自臨時伺服器 (https://addons.allizom.org/) 的資料啟動開發伺服器/代理程式（適用於 amo）
紗線結構	建立應用程式。
紗線構建-ci	運行build和bundlewatch npm 腳本。
紗線束表	執行bundlewatch以檢查產生的AMO套件大小。首先需要建造 AMO。
紗線流量	運行流程。預設情況下，這會檢查錯誤並退出
紗線流量：檢查	明確檢查 Flow 錯誤並退出
紗線流量：dev	持續檢查 Flow 錯誤
紗線 eslint	Lint JS
紗線啟動功能測試伺服器	啟動 Docker 容器進行功能測試
紗線風格皮棉	檢查 SCSS
紗線絨毛	運行所有 JS + SCSS linter
紗線更漂亮	運行 Prettier 自動格式化整個程式碼庫
紗線更漂亮的開發	運行 [Pretty-Quick][] 自動將修改後的來源檔案與 master 分支進行比較和格式化
紗線更漂亮-ci	如果某些程式碼未經格式化而被更改，則執行 Prettier 並失敗
紗線版本檢查	檢查您是否具有所需的依賴項
紗線測試	執行所有測試（在--watch模式下輸入 jest）
紗線測試調試	使用完整的控制台輸出和完整的錯誤訊息運行所有測試（在--watch模式下輸入 jest）
紗線測試覆蓋率	執行所有測試並產生程式碼覆蓋率報告（在--watch模式下輸入 jest）
紗線測試覆蓋率-一次	執行所有測試，產生程式碼覆蓋率報告，然後退出
紗線測試一次	執行所有測試，執行所有 JS + SCSS linter，然後退出
紗線測試-ci	運行所有持續集成檢查。這僅適用於 CI 上運行。

運行測試

您可以透過輸入yarn test或yarn test-debug進入互動式玩笑模式。這是開發新功能最簡單的方法。

以下是一些提示：

• yarn test將隱藏大多數控制台輸出和詳細的測試失敗訊息，因此最好在執行全套測試時使用。在進行單獨的測試時，您可能需要執行yarn test-debug 。
• 當您啟動yarn test時，您可以切換到程式碼編輯器並開始新增測試檔案或變更現有程式碼。當您儲存每個檔案時，jest 將僅執行與您變更的程式碼相關的測試。
• 如果您在第一次啟動時輸入了a ，那麼即使您更改了特定文件，jest 也會繼續運行整個套件。鍵入o切換回僅執行與您正在變更的檔案相關的測試的模式。
• 有時運行與文件更改相關的測試很慢。在這些情況下，您可以在修復特定測試套件時鍵入p或t按名稱過濾測試。更多資訊。
• 如果您在 Mac OS 上看到類似Error watching file for changes: EMFILE內容，則brew install watchman可能會修復它。參見 jestjs/jest#1767

運行測試的子集

預設情況下， yarn test將僅執行與您正在處理的程式碼相關的測試子集。

要明確運行測試子集，您可以鍵入t或p這在 jest watch 用法中進行了解釋。

或者，您可以使用特定檔案或正規表示式啟動測試運行程序，例如：

 yarn test tests/unit/amo/components/TestAddon.js

運行所有測試

如果您想執行所有測試並退出，請鍵入：

 yarn test-once

埃斯林特

當您執行測試時，您將在測試輸出末尾看到 Eslint 錯誤報告：

 yarn test

如果您想在沒有 Eslint 檢查的情況下執行測試，請設定環境變數：

 NO_ESLINT=1 yarn test

流動

使用 Flow 來驗證我們程式的意圖的支援有限。

當您執行測試時，您將在測試輸出末尾看到 Flow 錯誤報告：

 yarn test

如果您想在沒有 Flow 檢查的情況下執行測試，請設定一個環境變數：

 NO_FLOW=1 yarn test

若要僅在編輯文件時檢查開發期間的 Flow 問題，請執行：

 yarn flow:dev

如果您不熟悉 Flow，請參考以下提示：

• 請參閱入門指南。
• 通讀 web-ext 指南，以取得如何解決常見 Flow 錯誤的提示。

若要將流覆蓋新增至來源文件，請在頂部放置/* @flow */註釋。您可以選擇加入 Flow 的來源檔案越多越好。

這是我們的 Flow 宣言：

• 我們使用 Flow 來聲明程式碼的意圖並幫助其他人充滿信心地重構它。 Flow 還可以讓您更輕鬆地發現錯誤，然後再花數小時在偵錯器中嘗試找出發生的情況。
• 避免任何內部代碼的魔術流聲明。只需在使用它的程式碼旁邊聲明一個類型別名，然後像任何其他物件一樣匯出/匯入它。
• 切勿僅為了引用其類型而匯入真正的 JS 物件。建立一個類型別名並導入它。
• 切勿新增超出您所需的類型註解。 Flow 非常擅長從標準 JS 程式碼推斷類型；它會告訴您何時需要添加明確註釋。
• 當像getAllAddons這樣的函數接受物件參數時，呼叫其類型物件GetAllAddonsParams 。例子：

 type GetAllAddonsParams = { |
  categoryId : number ,
| } ;

function getAllAddons ( { categoryId } : GetAllAddonsParams = { } ) {
  ...
}

• 盡可能透過管道語法 ( {| key: ... |} ) 使用精確物件類型。有時，擴充運算子會觸發「不精確類型與精確類型不相容」之類的錯誤，但這是一個錯誤。如果需要，您可以使用src/amo/types/util中的Exact<T>解決方法。這是 $Exact 的有效替代品。
• 為 HOC（高階元件）中包裝的元件新增類型提示，以便 Flow 可以驗證對該元件的呼叫。我們需要添加一個提示，因為我們還沒有對我們依賴的所有 HOC 進行適當的類型覆蓋。這是一個例子：

 // Imagine this is something like components/ConfirmButton/index.js
import { compose } from 'redux' ;
import * as React from 'react' ;

// This expresses externally used props, i.e. to validate how the app would use <ConfirmButton />
type Props = { |
  prompt ?: string | null ,
| } ;

// This expresses internally used props, such as i18n which is injected by translate()
type InternalProps = { |
  ... Props ,
  i18n : I18nType ,
| } ;

export class ConfirmButtonBase extends React . Component < InternalProps > {
  render ( ) {
    const prompt = this . props . prompt || this . props . i18n . gettext ( 'Confirm' ) ;
    return < button > { prompt } < / button > ;
  }
}

// This provides a type hint for the final component with its external props.
// The i18n prop is not in external props because it is injected by translate() for internal use only.
const ConfirmButton : React . ComponentType < Props > = compose ( translate ( ) ) (
  ConfirmButtonBase ,
) ;

export default ConfirmButton ;

• 盡量避免像Object或any這樣的鬆散類型，但如果您花費太多時間聲明依賴其他類型的類型，而這些類型又依賴於其他類型，則可以隨意使用它們。
• 如果您遇到錯誤或遇到讓您頭撞鍵盤的問題，您可以新增$FlowFixMe註解來跳過 Flow 檢查。如果您認為無法修復，請改用$FlowIgnore 。請在評論中解釋你的理由，並在可能的情況下連結到 GitHub 問題。
• 如果您對某些 Flow 註解不起作用的原因感到困惑，請嘗試使用yarn flow type-at-pos ...命令來追蹤哪些類型應用於程式碼。有關詳細信息，請參閱yarn flow -- --help type-at-pos 。

更漂亮

我們使用 Prettier 自動格式化 JavaScript 程式碼並停止所有關於樣式的持續爭論。

程式碼覆蓋率

若要查看程式碼覆蓋率報告，請鍵入：

 yarn test-coverage-once

這將列印一個文件表，顯示程式碼覆蓋率的百分比。未覆蓋的行將顯示在右列中，但您可以在瀏覽器中開啟完整報告：

 open coverage/lcov-report/index.html

運作 AMO 促進本地發展

提供代理伺服器，用於在與前端相同的主機上運行帶有 API 的 AMO 應用程式。這模仿了我們的生產設定。

開始針對託管 API 進行開發，如下所示：

 yarn amo:dev

這會將代理程式配置為使用https://addons-dev.allizom.org來取得 API 資料。此命令是開發新前端功能最常見的方法。請參閱上面的命令表，以了解執行伺服器的類似方法。

若要使用在 Docker 中執行的本機 API 伺服器，您可以使用yarn amo命令。然而，目前這不起作用。請參閱問題 7196。

從 addons-frontend 啟動時身份驗證將起作用，並將持續到 addons-server，但從 addons-server 頁面登入時它將無法運作。有關修復此問題的更多信息，請參閱 mozilla/addons-server#4684。

本地配置

如果您需要在執行yarn amo 、 yarn amo:dev或yarn amo:stage時覆蓋任何設置，請先建立一個名稱與此完全相同的本機設定檔：

 touch config/local-development.js

進行任何配置變更。例如：

 module . exports = {
  trackingEnabled : true ,
} ;

重啟伺服器即可看到生效。

請參閱設定檔載入順序文件以了解有關如何套用設定的詳細資訊。

配置 Android 裝置以進行本機開發

如果您想在 Android 裝置上存取本機伺服器，您將需要更改一些設定。假設您的本機電腦可以在網路上透過 IP 位址10.0.0.1進行存取。你可以像這樣啟動你的伺服器：

 API_HOST=http://10.0.0.1:3000 
    SERVER_HOST=10.0.0.1 
    WEBPACK_SERVER_HOST=10.0.0.1 
    yarn amo:dev

然後，您可以在 Android 裝置上造訪開發網站http://10.0.0.1:3000 。

注意：目前無法使用此設定登錄，因為 Mozilla 帳戶用戶端重定向到localhost:3000 。您可以透過編輯裝置上的/etc/hosts來嘗試不同的方法，以便localhost指向您的開發計算機，但這尚未經過充分測試。

禁用 CSP 進行本地開發

當使用 webpack 伺服器進行本機開發時，隨機產生的資產 URL 將使我們的內容安全策略 (CSP) 失敗，並使您的控制台出現錯誤。您可以透過在任何本機設定檔（例如local-development-amo.js中將 CSP 設定為false來關閉所有 CSP 錯誤。例子：

 module . exports = {
  CSP : false ,
} ;

處理文件

現在您正在閱讀的文件以 Github 風格的 Markdown 形式存在於來源儲存庫中。當您對這些文件進行更改時，您可以建立拉取請求來預覽它們，或者更好的是，您可以使用grip 在本地預覽更改。安裝grip後，從來源目錄執行它，如下所示：

 grip .

開啟其localhost URL，您將看到已渲染的README.md檔案。當您進行編輯時，它會自動更新。

建置和運行服務

以下是部署中使用的腳本 - 通常不需要，除非您正在測試與部署或建置相關的內容。

環境變數是：

• NODE_ENV ：節點環境，例如production或development
• NODE_CONFIG_ENV ：要載入的設定的名稱，例如dev 、 stage 、 prod

腳本	描述
紗線開始	啟動 Express 伺服器（需要環境變數）
紗線結構	建置庫（所有應用程式）（需要環境變數）

範例：建置並運行應用程式的生產實例：

 NODE_ENV=production NODE_CONFIG_ENV=prod yarn build
NODE_ENV=production NODE_CONFIG_ENV=prod yarn start

在本地運行構建

要在生產模式下本地運行應用程序，您需要為本地生產建置建立一個設定檔。可以為不同的環境建立生產版本： dev 、 stage和prod （由NODE_CONFIG_ENV環境變數控制），但這些環境在本地運行只需要一個額外的設定檔。

將名為config/local.js.dist的檔案重新命名為config/local.js 。之後，請按照上面的說明使用yarn build和yarn start重新建置並重新啟動。如果您之前使用過127.0.0.1且配置不同，請務必清除您的 cookie。該應用程式應位於：http://127.0.0.1:4000/。

注意：目前無法使用此方法登入。

部署什麼版本？

您可以透過發出以下請求來檢查部署了哪些addons-frontend提交、哪些 A/B 實驗正在運行，或啟用了哪些功能標誌：

 curl https://addons-dev.allizom.org/__frontend_version__
{
    "build": "https://circleci.com/gh/mozilla/addons-frontend/10333",
    "commit": "47edfa6f24e333897b25516c587f504e294e8fa9",
    "experiments": {
        "homeHero": true
    },
    "feature_flags": {
        "enableFeatureAMInstallButton": true,
        "enableFeatureStaticThemes": true
    },
    "source": "https://github.com/mozilla/addons-frontend",
    "version": ""
}

如果根目錄中不存在version.json文件，這將傳回 415 回應。該文件通常由部署過程產生。

為了與監控腳本保持一致，可以透過以下 URL 檢索相同的資料：

 curl https://addons-dev.allizom.org/__version__

您可以安裝 amo-info 擴充功能來輕鬆查看此資訊。

插件 前端部落格 實用程式

該專案還包含用於建立名為addons-frontend-blog-utils的庫的程式碼，並提供以下命令：

• yarn build:blog-utils-dev ：建立庫，啟動觀察程序以在更改時重建庫，並在 http://127.0.0.1:11000 上提供開發頁面
• yarn build:blog-utils-prod ：在生產模式下建立庫

該庫專門設計用於與 addons-blog 配合使用。

發布流程

為了發布新版本的addons-frontend-blog-utils ，必須將一個特殊標籤推送到主儲存庫。標籤名稱必須以blog-utils-開頭，並且通常包含版本號碼。可以使用以下命令自動執行此操作：

 npm version [major|minor|patch]

從master分支發出此命令將更新package.json中的版本，建立提交並建立標籤。將此提交和標籤推送到主存儲庫。

注意：當新的addons-frontend-blog-utils版本合併到 addons-blog 中時，您應該發布新版本的 WordPress 主題。請按照 addons-blog 儲存庫中的這些說明進行操作。

核心技術

• 基於 Redux + React
• ES2015+ 編寫的程式碼
• 透過節點進行通用渲染
• 高覆蓋率的單元測試（目標是100%）