@bluelovers/jest-config 1.1.11 → 1.1.12

package/CHANGELOG.md

@@ -3,6 +3,49 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [1.1.12](https://github.com/bluelovers/ws-jest/compare/@bluelovers/jest-config@1.1.11...@bluelovers/jest-config@1.1.12) (2026-09-12)
+
+
+
+### ✨　Features
+
+* **@bluelovers/jest-config:** 重構配置邏輯並優化環境與轉換器設定 ([861fac6](https://github.com/bluelovers/ws-jest/commit/861fac6f8a2e0e5e1438b9cfd923c120a82690f3))
+* **@bluelovers/jest-config:** 新增 setupFiles 支援並優化依賴解析工具 ([093e468](https://github.com/bluelovers/ws-jest/commit/093e468ff09a923d78feb2329c6079a039910fc5))
+
+
+### 📚　Documentation
+
+* **jest-config:** 完善 JSDoc 文档和双语 README ([90b1e92](https://github.com/bluelovers/ws-jest/commit/90b1e92c35594b4601a1ec788d04d848de98ab4e))
+
+
+### 🚨　Tests
+
+* **@lazy-assert/jest-expect-matcher:** 新增 snapshot 檔案並重構測試結構 ([d371e65](https://github.com/bluelovers/ws-jest/commit/d371e6577c229db949e2e29f080d4bd4c81ed652))
+
+
+### 🛠　Build System
+
+* 升級開發工具鏈與優化 monorepo 配置 ([d5ec02d](https://github.com/bluelovers/ws-jest/commit/d5ec02de7c66ab9cc1ebbe693e9708c561c68c53))
+* **dist:** update build ([4afc40e](https://github.com/bluelovers/ws-jest/commit/4afc40e52c2dbf807ec50ccab179c969c36f270d))
+
+
+### ♻️　Chores
+
+* **workspace:** 更新 .gitignore 和描述信息 ([247fdee](https://github.com/bluelovers/ws-jest/commit/247fdee5667abc19bb11812d1870e4fb9180a675))
+* **workspace:** 迁移至 pnpm 并重构 Jest 配置 ([c09cfc7](https://github.com/bluelovers/ws-jest/commit/c09cfc7e4472b8f0357d45c1c34e57fddde6e1cc))
+
+
+### 📌　Dependencies
+
+* update deps ([a059d4f](https://github.com/bluelovers/ws-jest/commit/a059d4ffd6de4c2ed678ef2c1b1e1a3cf43ef3eb))
+
+
+### 🔖　Miscellaneous
+
+* . ([e93d019](https://github.com/bluelovers/ws-jest/commit/e93d019e665e5d65bae5536f00e8c57f80ed77df))
+
+
+
 ## [1.1.11](https://github.com/bluelovers/ws-jest/compare/@bluelovers/jest-config@1.1.10...@bluelovers/jest-config@1.1.11) (2023-11-16)
 
 

package/README.md

@@ -1,17 +1,216 @@
-# README.md
+# @bluelovers/jest-config
 
-    
+Jest configuration preset with TypeScript support, providing automatic ts-jest transform chain integration, cache management, and coverage settings.
 
-## install
+具備 TypeScript 支援的 Jest 配置預設套件，提供自動 ts-jest 轉換鏈整合、快取管理和覆蓋率設定。
+
+## 特色 / Features
+
+- **預設 Jest 配置 / Default Jest Configuration**: 包含完整的 TypeScript 測試環境設定
+- **ts-jest 轉換鏈 / ts-jest Transform Chain**: 自動整合 `jest-tsd-transform` 和 `jest-chain-transform`
+- **配置混合功能 / Configuration Mixing**: 透過 `mixinJestConfig` 函數輕鬆合併自定義配置
+- **快取目錄管理 / Cache Directory Management**: 自動管理 Jest 快取位置
+- **覆蓋率收集 / Coverage Collection**: 內建 v8 覆蓋率提供者設定
+
+## 安裝 / Installation
 
 ```bash
+# Using npm
+npm install @bluelovers/jest-config
+
+# Using yarn
 yarn add @bluelovers/jest-config
+
+# Using yarn-tool
 yarn-tool add @bluelovers/jest-config
+
+# Using yt (short for yarn-tool)
 yt add @bluelovers/jest-config
+
+# Using pnpm
+pnpm add @bluelovers/jest-config
+```
+
+## 使用方式 / Usage
+
+### 基本使用 / Basic Usage
+
+```javascript
+// jest.config.js
+const { mixinJestConfig } = require('@bluelovers/jest-config');
+
+module.exports = mixinJestConfig({
+  // 你的自定義配置 / Your custom configuration
+});
+```
+
+### TypeScript 使用 / TypeScript Usage
+
+```typescript
+// jest.config.ts
+import { mixinJestConfig } from '@bluelovers/jest-config';
+
+export default mixinJestConfig({
+  // 你的自定義配置 / Your custom configuration
+});
 ```
 
-support `jest-tsd-transform`
+### 顯示配置資訊 / Display Configuration Info
+
+```typescript
+import { mixinJestConfig } from '@bluelovers/jest-config';
+
+// 第二個參數設為 true 會自動印出配置資訊
+// Set second parameter to true to auto print config info
+export default mixinJestConfig({}, true);
+```
+
+### 支援的擴充套件 / Supported Extensions
+
+- [`jest-tsd-transform`](https://www.npmjs.com/package/jest-tsd-transform): TypeScript 宣告檔轉換 / TypeScript declaration file transformation
+- [`jest-chain-transform`](https://www.npmjs.com/package/jest-chain-transform): Jest 轉換鏈協調 / Jest transform chain coordination
 
 ```bash
 yarn add jest-tsd-transform jest-chain-transform
 ```
+
+## 配置選項 / Configuration Options
+
+| 選項 / Option | 說明 / Description | 預設值 / Default |
+|--------------|-------------------|-----------------|
+| `cacheDirectory` | Jest 快取目錄 / Jest cache directory | 自動偵測 / Auto-detected |
+| `maxWorkers` | 最大工作執行緒數量 / Maximum worker threads | `1` |
+| `clearMocks` | 是否清除模擬物件 / Clear mocks between tests | `true` |
+| `passWithNoTests` | 沒有測試時是否通過 / Pass when no tests found | `true` |
+| `moduleFileExtensions` | 模組檔案副檔名 / Module file extensions | `['js','mjs','cjs','jsx','ts','mts','cts','tsx','json','node']` |
+| `testPathIgnorePatterns` | 測試路徑忽略模式 / Test path ignore patterns | `['/node_modules/','/__fixtures__/','/dist/']` |
+| `setupFilesAfterEnv` | 環境設置後載入的檔案 / Files to load after environment setup | `[]` |
+| `coverageProvider` | 覆蓋率提供者 / Coverage provider | `'v8'` |
+| `collectCoverage` | 是否收集覆蓋率 / Collect coverage | `false` |
+| `coveragePathIgnorePatterns` | 覆蓋率路徑忽略模式 / Coverage path ignore patterns | `['/node_modules/','/__snapshots__/','/dist/']` |
+
+## API 參考 / API Reference
+
+### `mixinJestConfig(jestConfig?, autoPrint?, options?)`
+
+混合 Jest 配置的函數。
+Function for mixing Jest configurations.
+
+**參數 / Parameters:**
+
+- `jestConfig` (可選/optional): 使用者自定義的 Jest 配置 / User custom Jest configuration
+- `autoPrint` (可選/optional): 是否自動印出配置資訊 / Whether to auto print configuration info
+- `options` (可選/optional): 印出配置的選項 / Options for printing configuration
+
+**回傳值 / Returns:**
+
+- 合併後的完整 Jest 配置 / Merged complete Jest configuration
+
+**範例 / Example:**
+
+```typescript
+import { mixinJestConfig } from '@bluelovers/jest-config';
+
+const config = mixinJestConfig(
+  {
+    testEnvironment: 'jsdom',
+    setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
+  },
+  true, // 自動印出配置 / Auto print config
+  { cwd: __dirname } // 選項 / Options
+);
+```
+
+## 核心功能 / Core Features
+
+### 自動轉換鏈整合 / Automatic Transform Chain Integration
+
+此套件會自動偵測並整合以下轉換器：
+This package automatically detects and integrates the following transformers:
+
+1. **ts-jest**: 主要的 TypeScript 轉換器 / Primary TypeScript transformer
+2. **jest-tsd-transform**: TypeScript 宣告檔測試支援 / TypeScript declaration file testing support
+3. **jest-chain-transform**: 多層轉換協調 / Multi-layer transform coordination
+
+### 快取目錄管理 / Cache Directory Management
+
+使用 `jest-cache-directory` 自動選擇最佳的快取位置：
+Uses `jest-cache-directory` to automatically select the optimal cache location:
+
+- 優先使用本地 `node_modules/.cache/jest` / Prefer local `node_modules/.cache/jest`
+- 若不可寫入則使用系統暫存目錄 / Falls back to system temp directory if not writable
+
+### 測試檔案副檔名 / Test File Extensions
+
+預設支援的測試檔案副檔名：
+Default supported test file extensions:
+
+- `.ts` - TypeScript
+- `.tsx` - TypeScript with JSX
+- `.mts` - TypeScript ES Module
+- `.cts` - TypeScript CommonJS Module
+
+## 發布檔案結構 / Published File Structure
+
+### Jest Preset 檔案 / Jest Preset Files
+
+此套件發布時包含以下 Jest preset 檔案：
+The following Jest preset files are included when publishing this package:
+
+| 檔案 / File | 說明 / Description | 必要性 / Required |
+|------------|-------------------|------------------|
+| `jest-preset.cjs` | CommonJS 版本的 Jest preset | ✅ 必須 / Required |
+| `jest-preset.mjs` | ES Module 版本的 Jest preset | ✅ 必須 / Required |
+| `jest-preset.js` | 不需要實體檔案 / No physical file needed | ❌ 省略 / Omitted |
+
+### 為什麼 jest-preset.js 不需要？
+
+`package.json` 中的 `exports` 欄位已定義了虛擬路徑映射：
+The `exports` field in `package.json` defines virtual path mappings:
+
+```json
+{
+  "exports": {
+    "./jest-preset": {
+      "require": "./jest-preset.cjs",
+      "import": "./jest-preset.mjs"
+    },
+    "./jest-preset.js": {
+      "require": "./jest-preset.cjs",
+      "import": "./jest-preset.mjs"
+    }
+  }
+}
+```
+
+這表示無論使用者使用 `preset: '@bluelovers/jest-config'` 或 `preset: '@bluelovers/jest-config/jest-preset.js'`，
+Node.js 都會根據環境自動導向至正確的 `.cjs` 或 `.mjs` 檔案。
+
+This means whether users use `preset: '@bluelovers/jest-config'` or `preset: '@bluelovers/jest-config/jest-preset.js'`,
+Node.js will automatically resolve to the correct `.cjs` or `.mjs` file based on the environment.
+
+### .npmignore 配置
+
+確保以下檔案不被忽略：
+Ensure these files are not ignored:
+
+```gitignore
+# 保留 Jest preset 檔案 / Keep Jest preset files
+!jest-preset.*
+!jest-preset.cjs
+!jest-preset.mjs
+!jest.config.*
+jest.config.js
+```
+
+## 授權 / License
+
+ISC
+
+---
+
+## 相關連結 / Related Links
+
+- [GitHub 儲存庫 / Repository](https://github.com/bluelovers/ws-jest)
+- [問題回報 / Issue Tracker](https://github.com/bluelovers/ws-jest/issues)
+- [npm 套件頁面 / npm Package](https://www.npmjs.com/package/@bluelovers/jest-config)