【Next.js】Private Folders

在 Next.js 中，**Private Folders（私有資料夾）**是指：

🔒 不會被當作路由、自動產生頁面或靜態資源的資料夾。
這些資料夾的名稱 開頭是底線 _ 或雙底線 __，也就是說：

✅ 資料夾名稱開頭為 `_` 或 `__` ⇒ Next.js 會自動忽略它

🔍 什麼是 Private Folders？

這是 Next.js 的一項慣例（convention），用來 隔離你不想當作頁面處理的輔助程式碼或元件檔案。

📁 使用範例

假設你有以下結構：

app/
├── page.tsx
├── _utils/              ← ✅ 不會當成路由
│   └── formatter.ts
├── __tests__/           ← ✅ 不會當成路由
│   └── page.test.tsx

這些 _utils/、__tests__/ 都是 Private Folders：

不會產生 /utils 路由
不會被包含在 build 出來的頁面中
適合放測試、工具、常數、hooks 等程式碼

✅ 實用用途

資料夾名稱	用途範例
`_utils/`	放工具函式（e.g. dateFormat）
`_hooks/`	放自訂 React Hook
`__tests__/`	放單元測試
`__mocks__/`	放 Jest mock 資料

🧠 注意事項

行為	說明
✅ 允許 `import` 使用	Private folders 裡的檔案仍然可以被引用
❌ 不會產生 URL	不會出現像 `/__tests__` 這種頁面
✅ 適用於 `pages/` 與 `app/` 架構	兩種路由系統都支援
⚠️ 無法自訂規則	Next.js 只會根據 `_` 或 `__` 開頭自動判斷

📝 範例：使用 `_utils/format.ts`

// app/_utils/format.ts
export function formatCurrency(amount: number) {
  return `$${amount.toFixed(2)}`
}

// app/products/page.tsx
import { formatCurrency } from '../_utils/format'

export default function ProductPage() {
  return <p>{formatCurrency(123.456)}</p>
}

✅ 小結

項目	說明
命名規則	資料夾名稱開頭為 `_` 或 `__`
功能	不產生頁面、不加入 build 路由
適合用途	工具、hook、測試、mock、常數
是否能 import	✅ 可以被引用使用

~~需要我幫你設計一個實際的~~這是一個非常好也非常細緻的問題，牽涉到 ~~private~~JavaScript ~~folders~~/ ~~結構範本嗎？或搭配~~TypeScript ~~testing~~社群和工具生態中的 ~~library~~命名慣例（naming ~~使用？~~conventions），並不是 Next.js 特有的規定，而是社群共識。

🔍 TL;DR 結論

命名形式

用途 / 慣例來源 _folder 🔒 私有資料夾，Next.js 慣例（前綴式） Next.js、社群通用慣例 __tests__ ✅ 測試資料夾，Jest 標準結構（雙底線前後） Jest 官方 __mocks__ ✅ Mock 資料夾，Jest 標準 Jest _filename.ts 私有或輔助用檔案（非主模組） Node / TypeScript 社群

✅ 單底線 `_`：一般表示私有或特殊用途

_utils/、_hooks/、_internal/

表示：這不是一個路由，也不是 API 端點，只是輔助邏輯用

這種用法來自許多框架（Django、Rails、Node.js）與社群習慣。

✅ 雙底線 `__`：通常是工具/測試框架的保留命名

來自 Jest、React Native、Metro Bundler 等工具：

__tests__ → Jest 會自動找出來執行單元測試

__mocks__ → Jest 用來定義自動 mock 資料

__snapshots__ → Jest 的 snapshot 測試檔案

👉 雙底線前後一致，通常代表「這是特殊目的目錄」，會被工具偵測與處理。

🧠 命名語意總整理

命名

語意常見用途 _名稱 私有 / 忽略 / 特殊用途（Next.js 慣例） _utils, _internal, _api __名稱__ 測試工具專用 __tests__, __mocks__ 無底線公開模組 / 頁面 / API 等 products, user, api

✅ Next.js 怎麼處理這些命名？

資料夾名稱

是否會轉成路由？用途建議 products/ ✅ 是頁面 _products/ ❌ 否工具 / 非頁面模組 __tests__/ ❌ 否單元測試、快照測試用

📌 延伸知識：為何不是 `_tests/` 而是 `tests`？

這來自 Unix / Bash 與正規表達式處理的傳統：

__tests__ 這種明確結構更容易在工具中用 glob 匹配，如：
```
find . -name '__tests__'
jest "**/__tests__/**/*.test.tsx"
```

這是 Jest 與 Babel 的官方推薦格式。

✅ 總結

命名類型

意圖 / 工具支援 _xxx/ Next.js 私有目錄，僅開頭底線 __xxx__/ Jest 風格目錄，工具自動識別處理 _xxx.ts 單一檔案私有語意