【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	✅ 可以被引用使用

---

這是一個非常好也非常細緻的問題，牽涉到 JavaScript / TypeScript 社群和工具生態中的 命名慣例（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	單一檔案私有語意

---

此外通常utils 其他分類資料夾只要不在app 下就不會產生路由，也是一種常用的方法