PostCSS Runner 指南

PostCSS Runner 是一種透過使用者定義的外掛程式清單來處理 CSS 的工具；例如，postcss-cli 或 gulp‑postcss。這些規則對於任何此類 Runner 都是強制性的。

對於單一外掛程式工具，例如 gulp-autoprefixer，這些規則不是強制性的，但強烈建議遵循。

另請參閱 ClojureWerkz 的建議，以了解開放原始碼專案。

1. API

1.1. 接受外掛程式參數中的函式

如果 Runner 使用設定檔，則必須以 JavaScript 編寫，以便支援接受函式的外掛程式，例如 postcss-assets

module.exports = [
  require('postcss-assets')({
    cachebuster: function (file) {
      return fs.statSync(file).mtime.getTime().toString(16)
    }
  })
]

2. 處理

2.1. 設定 `from` 和 `to` 處理選項

為確保 PostCSS 產生來源地圖並顯示更佳的語法錯誤，Runner 必須指定 from 和 to 選項。如果 Runner 不處理寫入磁碟（例如，gulp 轉換），您應該設定兩個選項指向同一個檔案

processor.process({ from: file.path, to: file.path })

2.2. 僅使用非同步 API

PostCSS 執行器必須僅使用非同步 API。同步 API 僅用於除錯，速度較慢，且無法與非同步外掛程式搭配使用。

processor.process(opts).then(result => {
  // processing is finished
});

2.3. 僅使用公開的 PostCSS API

PostCSS 執行器不得依賴未記載的屬性或方法，這些屬性和方法可能會在任何次要版本中變更。公開 API 已在 API 文件中說明。

3. 相依關係

3.1. 當相依關係變更時重新建置

PostCSS 外掛程式可以透過將訊息附加到 result 來宣告檔案或目錄相依性。執行器應觀察這些相依性，並確保 CSS 在變更時會重新建置。

for (let message of result.messages) {
  if (message.type === 'dependency') {
    watcher.addFile(message.file)
  } else if (message.type === 'dir-dependency' && message.glob) {
    watcher.addPattern(file.join(message.dir, message.glob))
  } else if (message.type === 'dir-dependency') {
    watcher.addPattern(file.join(message.dir, '**', '*'))
  }
}

目錄應預設遞迴觀察，但 dir-dependency 訊息可能會包含一個選用的 glob 屬性，用來指出目錄中哪些檔案有相依性（例如 **/*.css）。如果指定了 glob，則執行器應僅觀察符合 glob 模式的檔案（如果可能）。

4. 輸出

4.1. 不要顯示 `CssSyntaxError` 的 JS 堆疊

PostCSS 執行器不得顯示 CSS 語法錯誤的堆疊追蹤，因為執行器可能由不熟悉 JavaScript 的開發人員使用。相反地，應妥善處理此類錯誤

processor.process(opts).catch(error => {
  if (error.name === 'CssSyntaxError') {
    process.stderr.write(error.message + error.showSourceCode())
  } else {
    throw error
  }
})

4.2. 顯示 `result.warnings()`

PostCSS 執行器必須輸出來自 result.warnings() 的警告

result.warnings().forEach(warn => {
  process.stderr.write(warn.toString())
})

另請參閱 postcss-log-warnings 和 postcss-messages 外掛程式。

4.3. 允許使用者將來源地圖寫入不同的檔案

PostCSS 預設會在產生的檔案中內嵌原始碼對應，但 PostCSS 執行器必須提供一個選項，讓使用者可以將原始碼對應儲存在不同的檔案中

if (result.map) {
  fs.writeFile(opts.to + '.map', result.map.toString())
}

5. 文件

5.1. 以英文撰寫 Runner 文件

PostCSS 執行器的 README.md 必須以英文撰寫。不要害怕自己的英文能力，因為開放原始碼社群會修正你的錯誤。

當然，歡迎你使用其他語言撰寫文件；只要適當地命名它們即可（例如 README.ja.md）。

5.2. 維護變更日誌

PostCSS 執行器必須在獨立檔案中描述所有版本的變更，例如 ChangeLog.md、History.md 或搭配 GitHub Releases 使用。請造訪 Keep A Changelog，深入瞭解如何撰寫其中一種檔案。

當然，您應該使用 SemVer。

5.3. `package.json` 中的 `postcss-runner` 關鍵字

為 npm 編寫的 PostCSS 執行器必須在 package.json 中包含 postcss-runner 關鍵字。此特殊關鍵字有助於提供 PostCSS 生態系統的回饋。

對於未發布至 npm 的套件，這並非強制規定，但如果套件格式允許包含關鍵字，則建議這麼做。

5.4. 將 `postcss` 保持在 `peerDependencies` 中

由於不同外掛程式中 postcss 版本不同，可能會導致 AST 損毀。不同外掛程式可以使用不同的節點建立器（例如 postcss.decl()）。

{
  "peerDependencies": {
    "postcss": "^8.0.0"
  }
}