> ## Documentation Index
> Fetch the complete documentation index at: https://extension.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 為瀏覽器擴充功能 CSS 使用 Stylelint

> 及早攔截 CSS 問題，並讓擴充功能各介面的樣式表品質維持一致。Stylelint 透過 scripts 或 CI 在 Extension.js 建置之外執行。

跨擴充功能各介面維持樣式表品質的一致性，並及早攔截 CSS 問題。Stylelint 會透過 scripts 或持續整合（CI）執行，而不是透過 Extension.js 的 dev/build pipeline。

## 什麼情況下適合使用 Stylelint

* 你在多個擴充功能介面之間維護共用的 CSS/Sass/Less。
* 你希望在 pull request 合併前進行樣式品質檢查。
* 你需要在團隊流程中維持一致的樣式表慣例。

## Stylelint 能做到的事

| 能力             | 帶來什麼好處                   |
| -------------- | ------------------------ |
| CSS 品質檢查       | 抓出不合法的寫法並強制套用樣式慣例        |
| 預處理器支援         | 在同一流程中檢查 CSS、Sass 與 Less |
| 與 Script、CI 整合 | 在合併與發佈前執行樣式檢查            |
| 與格式化工具對齊       | 與 Prettier 搭配以減少樣式工具的衝突  |

## 範本範例

### Stylelint 設定範本

預先設定好的樣式檢查範本。

<img src="https://mintcdn.com/extensionjs/VCnDd7fX2Nza24SE/images/examples/new-config-stylelint/screenshot.png?fit=max&auto=format&n=VCnDd7fX2Nza24SE&q=85&s=e07b3aebbd0465e61ae78e79cc3cb89e" alt="new-config-stylelint screenshot" width="2400" height="1800" data-path="images/examples/new-config-stylelint/screenshot.png" />

<CodeGroup>
  ```bash npm theme={null}
  npx extension@latest create my-extension --template=new-config-stylelint
  ```

  ```bash pnpm theme={null}
  pnpx extension@latest create my-extension --template=new-config-stylelint
  ```

  ```bash yarn theme={null}
  yarn dlx extension@latest create my-extension --template=new-config-stylelint
  ```

  ```bash bun theme={null}
  bunx extension@latest create my-extension --template=new-config-stylelint
  ```

  ```bash bun theme={null}
  bunx extension@latest create my-extension --template=new-config-stylelint
  ```
</CodeGroup>

Repository: [examples/new-config-stylelint](https://github.com/extension-js/examples/tree/main/examples/new-config-stylelint)

## 在既有擴充功能中使用

安裝 Stylelint 相依套件：

<PackageManagerTabs command="install -D stylelint stylelint-config-standard-scss" />

### Stylelint 設定

在專案根目錄建立 Stylelint 設定檔（例如 `.stylelintrc.json`）：

```json theme={null}
{
  "extends": "stylelint-config-standard-scss",
  "rules": {
    "color-no-invalid-hex": true,
    "block-no-empty": true
  }
}
```

### 執行 Stylelint

<CodeGroup>
  ```bash npm theme={null}
  npm run lint:styles
  ```

  ```bash pnpm theme={null}
  pnpm lint:styles
  ```

  ```bash yarn theme={null}
  yarn lint:styles
  ```

  ```bash bun theme={null}
  bun run lint:styles
  ```

  ```bash bun theme={null}
  bun run lint:styles
  ```
</CodeGroup>

如果尚未建立對應的 script：

<PackageManagerTabs command="stylelint '**/*.{css,scss,sass,less}'" />

## 與 Prettier 整合

將 Stylelint 與 Prettier 整合，一起格式化與檢查樣式。安裝下列相依套件：

<PackageManagerTabs command="install -D stylelint-prettier prettier" />

接著更新 `.stylelintrc.json` 以納入 Prettier：

```json theme={null}
{
  "extends": [
    "stylelint-config-standard-scss",
    "stylelint-prettier/recommended"
  ]
}
```

這樣可讓樣式格式化與檢查維持一致。

## 最佳實務

* 維持一個專屬的 `lint:styles` 指令，並在 CI 中執行。
* 在 monorepo 中跨擴充功能套件共用同一份設定。
* 將 Stylelint 與 Prettier 搭配使用，讓樣式格式化結果可預期。

## 偵測機制

Extension.js 能偵測 Stylelint 設定檔以進行診斷／報告，但不會把 Stylelint 注入建置 pipeline。

## 下一步

* 了解如何把 [Prettier](/docs/integrations/prettier) 整合進你的格式化流程。
* 為樣式表轉換設定 [PostCSS](/docs/integrations/postcss)。