ESLint Simple Import Sort - 排序你的專案 import

在 JavaScript 專案中，隨著檔案規模逐漸變大，外部與內部的依賴也會隨之增加，需要引入的套件、模組與工具自然越來越多。

在多數情況下，工程師不會特別去整理 import 的順序，但長期下來，這種隨意排列的方式其實會造成不少問題。

import 未統一排序可能帶來的問題

1. 可讀性降低 不同檔案的 import 排序方式不一致，會讓人難以快速理解每個 import 的來源。 如果能統一排序規則，就能立即分辨哪些是第三方套件、哪些是內部模組、哪些是相對路徑，並快速掌握該檔案的依賴關係。
2. 開發體驗下降 新成員加入時，需要額外時間適應團隊的 import 撰寫習慣。 在追蹤 bug 或重構程式碼時，也會因 import 混亂而難以快速釐清相關依賴。
3. 多人協作不一致 若缺乏統一規範，每個人依照自己的風格排序 imports，容易產生不必要的 diff，甚至增加合併衝突的風險。 若能透過工具自動排序，便能維持整個團隊的一致性。

例如下面這種情況（相信有不少人專案都長這樣ＸＤ）：

import { localValue } from './local-value'
import '@/polyfills'
import { queryClient } from '@/lib/query-client'
import { demoValue } from '../demo-value'
import 'dotenv/config'
import fs from 'node:fs'
import './import-sort-test.css'
import { buttonVariants } from '@/components/ui/button'
import { useFeatureFlag } from '@/hooks/use-feature-flag'
import { unknownPkg } from 'some-unknown-package'
import { getDecisionService } from '@/services/decision-service'
import { formatDecision } from '@/utils/format-decision'
import path from 'node:path'
import { createFileRoute } from '@tanstack/react-router'
import { userInternalHook } from '@/hooks/user-internal-hook'

為了解決這些問題，我們可以使用 simple-import-sort 這個 ESLint 插件。

simple-import-sort 是什麼？

simple-import-sort 是一個針對 ESLint 的插件，它提供以下功能：

• 自動按照規則排序 import（可分組、定義優先順序）
• 可以排序 export
• 可搭配 eslint --fix 自動修正排序問題。
• 自動處理 comments

而且他的配置方式相當簡單。

透過這個插件，我們可以輕鬆統一團隊的 import 排序規則，避免人為差異。

如何安裝與使用 simple-import-sort

1. 安裝

我們可以使用 npm 安裝：

npm install --save-dev eslint-plugin-simple-import-sort

2. Eslint 配置

接著就可以配置 eslint 規則了，以 .eslint.config.js 為例，

先引入 我們可以這樣使用：

import simpleImportSort from "eslint-plugin-simple-import-sort";

export default [
  {
    plugins: {
      "simple-import-sort": simpleImportSort,
    },
    rules: {
      "simple-import-sort/imports": "error",
      "simple-import-sort/exports": "error",
    },
  },
];

這樣設定後，只要執行 ESLint 搭配 --fix，就會自動修正 import 和 export 的排序。

3. 自訂分組排序

如果希望更精細地控制 import 順序，甚至在不同類型之間自動插入空行，可以透過 groups 進行設定。

這也是 simple-import-sort 的一大優勢：能以正則表達式定義不同類型的 import 群組順序。

例如，以下設定會依序引入副作用 import、第三方套件、內部模組、絕對路徑、相對路徑與樣式檔案：

rules: {
  'simple-import-sort/imports': [
    'error',
    {
      groups: [
        // 副作用 import 置頂
        ['^\\\\u0000'],
        // 第三方套件
        ['^react', '^@?\\\\w'],
        // 內部共享庫
        ['^@libs/'],
        // 絕對路徑
        ['^\\\\$src/'],
        // 相對路徑
        ['^\\\\.'],
        // 樣式檔案
        ['^.+\\\\.(css|scss)$'],
      ],
    },
  ],
}

每個群組內的 import 會再依字母順序排序，而不同群組之間則會自動加上空行，讓結構更加清楚。

讓 simple-import-sort 自動修正

如果你使用 VS Code，可以搭配 ESLint 插件，在存檔時直接自動執行 eslint --fix，來達到自動整理 import 的效果。

1. 先安裝 ESLint 插件：

2. 設定 settings.json

接著只要在 .vscode/settings.json 設定 source.fixAll.eslint 即可：

{
	"editor.codeActionsOnSave": {
	  "source.fixAll.eslint": true
	}
}

建議加上 validate 讓 vscode 對指定檔案即時啟用 ESLint：

{
	"eslint.validate": [
	  "javascript",
	  "javascriptreact",
	  "typescript",
	  "typescriptreact"
	],
}

如果你在配置 Monorepo，需要加上 eslint.workingDirectories 讓 ESLint 插件自動推斷當前檔案相關的 ESLint 配置

{
 "eslint.workingDirectories": [
    {
      "mode": "auto"
    }
  ]
}

配置完後，每次儲存時就會自動排序 imports 了，就像這樣，非常乾淨：

import '@/polyfills'
import 'dotenv/config'

import fs from 'node:fs'
import path from 'node:path'

import { createFileRoute } from '@tanstack/react-router'
import { unknownPkg } from 'some-unknown-package'

import { buttonVariants } from '@/components/ui/button'
import { useFeatureFlag } from '@/hooks/use-feature-flag'
import { userInternalHook } from '@/hooks/user-internal-hook'
import { queryClient } from '@/lib/query-client'
import { getDecisionService } from '@/services/decision-service'
import { formatDecision } from '@/utils/format-decision'

import { demoValue } from '../demo-value'

import { localValue } from './local-value'

import './import-sort-test.css'

小結

simple-import-sort 是一個針對 JavaScript 進行 import 及 export 排序的 ESLint 插件。它可以：

• 通過自動化工具提升程式碼一致性與可讀性
• 按類別分組並在同組內排序
• 在 IDE 儲存時結合 ESLint 自動整理

尤其對於中大型專案、多名開發者合作維護的場景，這種自動排序工具能夠減少 import 混亂所帶來額外的認知負擔或維護成本。

或許這對某些開發者來說沒什麼大不了的，但長期累積下來，他絕對能節省維護或追蹤 Bug 的時間、經歷。

馬上去試試看吧！