deps-conflict-resolver 1.0.0 → 1.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.en.md +315 -0
- package/README.md +83 -16
- package/dist/{config.types-CN7glPbA.d.cts → config.types-DPfKh8_B.d.cts} +21 -5
- package/dist/{config.types-CN7glPbA.d.ts → config.types-DPfKh8_B.d.ts} +21 -5
- package/dist/index.cjs +1199 -293
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +7 -7
- package/dist/index.d.ts +7 -7
- package/dist/index.js +1201 -295
- package/dist/index.js.map +1 -1
- package/dist/{resolver-BjbDmC24.d.ts → resolver-BBrA-8me.d.ts} +31 -1
- package/dist/{resolver-Dew5GU0y.d.cts → resolver-Bres_MgX.d.cts} +31 -1
- package/dist/vite.cjs +1216 -313
- package/dist/vite.cjs.map +1 -1
- package/dist/vite.d.cts +1 -1
- package/dist/vite.d.ts +1 -1
- package/dist/vite.js +1218 -315
- package/dist/vite.js.map +1 -1
- package/dist/webpack.cjs +1310 -334
- package/dist/webpack.cjs.map +1 -1
- package/dist/webpack.d.cts +11 -2
- package/dist/webpack.d.ts +11 -2
- package/dist/webpack.js +1312 -336
- package/dist/webpack.js.map +1 -1
- package/package.json +73 -44
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 ben-lau
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.en.md
ADDED
|
@@ -0,0 +1,315 @@
|
|
|
1
|
+
# deps-conflict-resolver
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/deps-conflict-resolver)
|
|
4
|
+
[](https://github.com/ben-lau/deps-conflict-resolver/actions/workflows/ci.yml)
|
|
5
|
+
[](https://codecov.io/gh/ben-lau/deps-conflict-resolver)
|
|
6
|
+
|
|
7
|
+
> [中文文档](./README.md)
|
|
8
|
+
|
|
9
|
+
A Webpack and Vite plugin that automatically resolves peer dependency conflicts by creating aliases for conflicting versions, allowing different versions of the same dependency to coexist.
|
|
10
|
+
|
|
11
|
+
## Features
|
|
12
|
+
|
|
13
|
+
- **Recursive Dependency Analysis**: Deep traversal of the entire dependency tree, including nested sub-dependencies
|
|
14
|
+
- **Smart Conflict Detection**: Automatically identifies peer dependency version conflicts against the host project
|
|
15
|
+
- **Automatic Alias Installation**: Creates aliases for conflicting dependencies and installs the appropriate versions
|
|
16
|
+
- **Module Resolution Redirection**: At build time, redirects module imports from conflicting libraries to their aliased versions
|
|
17
|
+
- **Remote Version Querying**: Fetches version lists from the npm registry and intelligently selects the best version
|
|
18
|
+
- **Webpack & Vite Support**: Provides plugin implementations for both build tools
|
|
19
|
+
|
|
20
|
+
## Use Case
|
|
21
|
+
|
|
22
|
+
The canonical scenario: your Vue 3 project needs to use a third-party library that only supports Vue 2. The library's dependency chain may include Vue 2, vue-router 3, and other older dependencies. This plugin can:
|
|
23
|
+
|
|
24
|
+
1. Automatically detect these version conflicts
|
|
25
|
+
2. Create aliases for conflicting dependencies (e.g., `aliased-vue2` for `vue@2.x`)
|
|
26
|
+
3. Automatically install the aliased dependencies
|
|
27
|
+
4. Redirect module resolution at build time: `import Vue from 'vue'` inside the third-party library resolves to `vue@2.x`, while the same import in your host project still resolves to `vue@3.x`
|
|
28
|
+
|
|
29
|
+
## Installation
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
npm install deps-conflict-resolver --save-dev
|
|
33
|
+
# or
|
|
34
|
+
yarn add deps-conflict-resolver -D
|
|
35
|
+
# or
|
|
36
|
+
pnpm add deps-conflict-resolver -D
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Usage
|
|
40
|
+
|
|
41
|
+
### Vite
|
|
42
|
+
|
|
43
|
+
```typescript
|
|
44
|
+
// vite.config.ts
|
|
45
|
+
import { defineConfig } from 'vite';
|
|
46
|
+
import { depsConflictResolverVitePlugin } from 'deps-conflict-resolver/vite';
|
|
47
|
+
|
|
48
|
+
export default defineConfig({
|
|
49
|
+
plugins: [
|
|
50
|
+
depsConflictResolverVitePlugin({
|
|
51
|
+
// Packages to analyze
|
|
52
|
+
dependencies: ['legacy-vue2-library'],
|
|
53
|
+
|
|
54
|
+
// Optional
|
|
55
|
+
autoInstall: true, // Auto-install missing aliased dependencies
|
|
56
|
+
packageManager: 'npm', // npm | yarn | pnpm
|
|
57
|
+
debug: false, // Enable debug logging
|
|
58
|
+
}),
|
|
59
|
+
],
|
|
60
|
+
});
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### Webpack
|
|
64
|
+
|
|
65
|
+
```typescript
|
|
66
|
+
// webpack.config.js
|
|
67
|
+
const { DepsConflictResolverWebpackPlugin } = require('deps-conflict-resolver/webpack');
|
|
68
|
+
|
|
69
|
+
module.exports = {
|
|
70
|
+
plugins: [
|
|
71
|
+
new DepsConflictResolverWebpackPlugin({
|
|
72
|
+
dependencies: ['legacy-vue2-library'],
|
|
73
|
+
autoInstall: true,
|
|
74
|
+
packageManager: 'npm',
|
|
75
|
+
}),
|
|
76
|
+
],
|
|
77
|
+
};
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
### Programmatic Usage
|
|
81
|
+
|
|
82
|
+
```typescript
|
|
83
|
+
import { createResolver } from 'deps-conflict-resolver';
|
|
84
|
+
|
|
85
|
+
const resolver = await createResolver({
|
|
86
|
+
dependencies: ['legacy-vue2-library'],
|
|
87
|
+
projectRoot: process.cwd(),
|
|
88
|
+
autoInstall: true,
|
|
89
|
+
});
|
|
90
|
+
|
|
91
|
+
// Get analysis results
|
|
92
|
+
const result = resolver.getAnalysisResult();
|
|
93
|
+
console.log('Peer conflicts:', result.peerConflicts);
|
|
94
|
+
console.log('Alias mappings:', result.aliasMappings);
|
|
95
|
+
|
|
96
|
+
// Manually resolve a module
|
|
97
|
+
const resolved = resolver.resolveModule('vue', '/path/to/importer.js');
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
## Configuration
|
|
101
|
+
|
|
102
|
+
| Option | Type | Default | Description |
|
|
103
|
+
| ------------------ | ------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
104
|
+
| `dependencies` | `string[]` | - | **Required.** List of package names to analyze |
|
|
105
|
+
| `projectRoot` | `string` | `process.cwd()` | Project root directory path |
|
|
106
|
+
| `autoInstall` | `boolean` | `true` | Whether to auto-install missing aliased dependencies |
|
|
107
|
+
| `packageManager` | `'auto' \| 'npm' \| 'yarn' \| 'pnpm'` | `'auto'` | Package manager type. `'auto'` detects automatically |
|
|
108
|
+
| `registry` | `string` | Auto-detected | npm registry URL. Falls back to `.npmrc` if not specified |
|
|
109
|
+
| `debug` | `boolean` | `false` | Whether to enable debug logging |
|
|
110
|
+
| `aliasPrefix` | `string` | `'aliased-'` | Prefix for generated alias names |
|
|
111
|
+
| `excludeRedirects` | `Record<string, string[]>` | `{}` | Exclude specific packages from the redirect list. Keys are original package names, values are importer package names to exclude. Example: `{ vue: ['vue-demi', 'pinia'] }` |
|
|
112
|
+
| `includeRedirects` | `Record<string, string[]>` | `{}` | Force specific packages into the redirect list. Applied before `excludeRedirects`. Useful when semver ranges are too broad (e.g., `>=2.5.0`) but the package still needs the older version at runtime. Example: `{ vue: ['@rili/ui', '@kmt/meeting-setting'] }` |
|
|
113
|
+
|
|
114
|
+
### Vite Plugin Exclusive Options
|
|
115
|
+
|
|
116
|
+
| Option | Type | Default | Description |
|
|
117
|
+
| --------------- | --------- | ------- | ------------------------------------------ |
|
|
118
|
+
| `enableInDev` | `boolean` | `true` | Whether to enable in development mode |
|
|
119
|
+
| `enableInBuild` | `boolean` | `true` | Whether to enable in production build mode |
|
|
120
|
+
|
|
121
|
+
### Auto-Detection
|
|
122
|
+
|
|
123
|
+
The plugin supports automatic detection of the package manager and registry:
|
|
124
|
+
|
|
125
|
+
**Package Manager Detection Priority:**
|
|
126
|
+
|
|
127
|
+
1. `packageManager` field in `package.json` (e.g., `"pnpm@8.0.0"`)
|
|
128
|
+
2. Lock file presence (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `package-lock.json` → npm)
|
|
129
|
+
3. Falls back to npm
|
|
130
|
+
|
|
131
|
+
**Registry Detection Priority:**
|
|
132
|
+
|
|
133
|
+
1. Project-level `.npmrc` file
|
|
134
|
+
2. User-level `~/.npmrc` file
|
|
135
|
+
3. `.yarnrc.yml` in yarn projects
|
|
136
|
+
4. Falls back to `https://registry.npmjs.org`
|
|
137
|
+
|
|
138
|
+
## How It Works
|
|
139
|
+
|
|
140
|
+
### 1. Dependency Analysis
|
|
141
|
+
|
|
142
|
+
The plugin recursively analyzes the entire dependency tree of the specified packages:
|
|
143
|
+
|
|
144
|
+
```
|
|
145
|
+
package-a
|
|
146
|
+
├── package-b
|
|
147
|
+
│ └── package-c (peerDeps: vue@^2.0.0)
|
|
148
|
+
└── package-d (peerDeps: vue-router@^3.0.0)
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
### 2. Conflict Detection
|
|
152
|
+
|
|
153
|
+
Compares installed versions in the host project against peer dependency requirements:
|
|
154
|
+
|
|
155
|
+
- Host project: `vue@3.2.0`, `vue-router@4.1.0`
|
|
156
|
+
- Peer dependency requirements: `vue@^2.0.0`, `vue-router@^3.0.0`
|
|
157
|
+
- Conflict detected ✗
|
|
158
|
+
|
|
159
|
+
### 3. Version Resolution
|
|
160
|
+
|
|
161
|
+
Fetches available versions from the npm registry and selects the best version that satisfies all peer dependency ranges:
|
|
162
|
+
|
|
163
|
+
- `vue@^2.0.0` → selects `vue@2.7.14`
|
|
164
|
+
- `vue-router@^3.0.0` → selects `vue-router@3.6.5`
|
|
165
|
+
|
|
166
|
+
### 4. Alias Installation
|
|
167
|
+
|
|
168
|
+
Creates and installs aliased dependencies:
|
|
169
|
+
|
|
170
|
+
```bash
|
|
171
|
+
npm install aliased-vue2@npm:vue@2.7.14
|
|
172
|
+
npm install aliased-vue-router3@npm:vue-router@3.6.5
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
### 5. Module Resolution Redirection
|
|
176
|
+
|
|
177
|
+
At build time, module imports are automatically redirected:
|
|
178
|
+
|
|
179
|
+
```javascript
|
|
180
|
+
// Inside package-c
|
|
181
|
+
import Vue from 'vue'; // → resolves to aliased-vue2
|
|
182
|
+
|
|
183
|
+
// In the host project
|
|
184
|
+
import Vue from 'vue'; // → resolves to vue (3.x)
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
### Behavioral Boundaries
|
|
188
|
+
|
|
189
|
+
- **Conflict Detection Scope**: Only the first-level `peerDependencies` of user-specified `dependencies` are checked for version conflicts against the host project. Sub-dependency `peerDependencies` do not trigger alias installation.
|
|
190
|
+
- **Redirect Scope**: Packages that declare conflicting peers and all their sub-dependencies (`dependencies` + `peerDependencies` recursively) are added to the redirect candidate list. The conflict target packages themselves (e.g., `vue`, `vue-router`) are automatically excluded during collection to prevent host project imports from being incorrectly redirected.
|
|
191
|
+
- **`excludeRedirects`**: Removes specified packages from the redirect candidate list. Useful for shared packages (e.g., `vue-demi`, `pinia`) that actually use the host's Vue 3 version at runtime.
|
|
192
|
+
- **`includeRedirects`**: Forces specified packages into the redirect list. Useful when semver ranges are too broad (e.g., `vue: ">=2.5.0"` satisfies both Vue 2 and Vue 3) but the package still needs the older version at runtime. `includeRedirects` is applied before `excludeRedirects`.
|
|
193
|
+
- **Alias Installation**: Aliases are only auto-installed for dependencies that are "declared by the host project with a version conflict." Undeclared peer dependencies only emit a warning without auto-installation.
|
|
194
|
+
- **Dependency Graph Deduplication**: The dependency tree traversal deduplicates by package name (each package is analyzed only once). In rare cases where multiple different versions of the same package name are nested, only the first resolved version is analyzed. This has minimal impact on redirect results since redirect matching is based on package name, not version.
|
|
195
|
+
|
|
196
|
+
## Advanced Usage
|
|
197
|
+
|
|
198
|
+
### Hooks
|
|
199
|
+
|
|
200
|
+
```typescript
|
|
201
|
+
depsConflictResolverVitePlugin({
|
|
202
|
+
dependencies: ['legacy-lib'],
|
|
203
|
+
hooks: {
|
|
204
|
+
// After analysis completes
|
|
205
|
+
onAnalysisComplete: (result) => {
|
|
206
|
+
console.log('Found conflicts:', result.peerConflicts);
|
|
207
|
+
},
|
|
208
|
+
|
|
209
|
+
// After installation completes
|
|
210
|
+
onInstallComplete: (installed) => {
|
|
211
|
+
console.log('Installed aliases:', installed);
|
|
212
|
+
},
|
|
213
|
+
|
|
214
|
+
// Custom module resolution
|
|
215
|
+
beforeResolve: (source, importer) => {
|
|
216
|
+
// Return a new module name, or null to skip
|
|
217
|
+
if (source === 'special-module') {
|
|
218
|
+
return 'custom-alias';
|
|
219
|
+
}
|
|
220
|
+
return null;
|
|
221
|
+
},
|
|
222
|
+
},
|
|
223
|
+
});
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
### Fine-Grained Redirect Control (includeRedirects + excludeRedirects)
|
|
227
|
+
|
|
228
|
+
When a project contains both Vue 2 and Vue 3 dependencies, auto-detection may not accurately distinguish them. Use these two options for manual control:
|
|
229
|
+
|
|
230
|
+
```typescript
|
|
231
|
+
new DepsConflictResolverWebpackPlugin({
|
|
232
|
+
dependencies: ['@uikit/vue-finder', '@rili/ui'],
|
|
233
|
+
|
|
234
|
+
// Force these packages (broad semver range, but actually need Vue 2) into the redirect list
|
|
235
|
+
includeRedirects: {
|
|
236
|
+
vue: ['@rili/ui', '@kmt/meeting-setting'],
|
|
237
|
+
},
|
|
238
|
+
|
|
239
|
+
// Exclude these packages from the redirect list (they use the host's Vue 3 at runtime)
|
|
240
|
+
excludeRedirects: {
|
|
241
|
+
vue: ['vue-demi', 'pinia', '@ks-email/editor'],
|
|
242
|
+
},
|
|
243
|
+
|
|
244
|
+
aliasPrefix: 'never-ever-gonna-import-',
|
|
245
|
+
autoInstall: true,
|
|
246
|
+
});
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
Priority: `includeRedirects` is applied first, then `excludeRedirects`. If the same package appears in both, `excludeRedirects` wins (not redirected).
|
|
250
|
+
|
|
251
|
+
### Reusing Existing Aliases
|
|
252
|
+
|
|
253
|
+
If the project already has aliases installed with suitable versions (e.g., `vue2@npm:vue@2.6.14`), the plugin will automatically detect and reuse them without reinstalling.
|
|
254
|
+
|
|
255
|
+
## API Reference
|
|
256
|
+
|
|
257
|
+
### `createResolver(options): Promise<DepsConflictResolver>`
|
|
258
|
+
|
|
259
|
+
Creates and initializes a dependency resolver.
|
|
260
|
+
|
|
261
|
+
### `DepsConflictResolver`
|
|
262
|
+
|
|
263
|
+
Main resolver class:
|
|
264
|
+
|
|
265
|
+
- `initialize(): Promise<void>` — Initialize the resolver
|
|
266
|
+
- `resolveModule(request, importer): string | null` — Resolve a module
|
|
267
|
+
- `getAnalysisResult(): AnalysisResult` — Get the analysis result
|
|
268
|
+
- `getAliasPathMappings(): AliasPathMapping[]` — Get generic alias path mappings
|
|
269
|
+
|
|
270
|
+
> The core module returns a generic `AliasPathMapping[]` format, which each build tool plugin (Webpack/Vite) converts to its own alias configuration format.
|
|
271
|
+
|
|
272
|
+
### Utility Functions
|
|
273
|
+
|
|
274
|
+
To minimize the public API surface and improve tree-shaking, internal utility functions (semver, fs, npm registry, etc.) are no longer exported from the main entry point. For capabilities like version comparison, use the `semver` package directly.
|
|
275
|
+
|
|
276
|
+
## Development
|
|
277
|
+
|
|
278
|
+
```bash
|
|
279
|
+
# Install dependencies
|
|
280
|
+
pnpm install
|
|
281
|
+
|
|
282
|
+
# Development mode
|
|
283
|
+
pnpm dev
|
|
284
|
+
|
|
285
|
+
# Build
|
|
286
|
+
pnpm build
|
|
287
|
+
|
|
288
|
+
# Run tests
|
|
289
|
+
pnpm test
|
|
290
|
+
|
|
291
|
+
# Type checking
|
|
292
|
+
pnpm typecheck
|
|
293
|
+
|
|
294
|
+
# Lint
|
|
295
|
+
pnpm lint
|
|
296
|
+
|
|
297
|
+
# Format
|
|
298
|
+
pnpm fmt
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
## Release Process
|
|
302
|
+
|
|
303
|
+
This project uses [release-please](https://github.com/googleapis/release-please) for automated releases:
|
|
304
|
+
|
|
305
|
+
1. Merge commits to `main` following [Conventional Commits](https://www.conventionalcommits.org/)
|
|
306
|
+
2. release-please automatically creates/updates a Release PR with changelog
|
|
307
|
+
3. Review and merge the Release PR
|
|
308
|
+
4. A GitHub Release + tag is automatically created
|
|
309
|
+
5. Manually run `npm publish` to publish to npm
|
|
310
|
+
|
|
311
|
+
See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
|
|
312
|
+
|
|
313
|
+
## License
|
|
314
|
+
|
|
315
|
+
MIT
|
package/README.md
CHANGED
|
@@ -1,5 +1,11 @@
|
|
|
1
1
|
# deps-conflict-resolver
|
|
2
2
|
|
|
3
|
+
[](https://www.npmjs.com/package/deps-conflict-resolver)
|
|
4
|
+
[](https://github.com/ben-lau/deps-conflict-resolver/actions/workflows/ci.yml)
|
|
5
|
+
[](https://codecov.io/gh/ben-lau/deps-conflict-resolver)
|
|
6
|
+
|
|
7
|
+
> [English Documentation](./README.en.md)
|
|
8
|
+
|
|
3
9
|
一个支持 Webpack 和 Vite 的插件,自动解析 peer 依赖冲突,通过创建别名来支持不同版本的依赖共存。
|
|
4
10
|
|
|
5
11
|
## 功能特性
|
|
@@ -93,15 +99,24 @@ const resolved = resolver.resolveModule('vue', '/path/to/importer.js');
|
|
|
93
99
|
|
|
94
100
|
## 配置选项
|
|
95
101
|
|
|
96
|
-
| 选项
|
|
97
|
-
|
|
|
98
|
-
| `dependencies`
|
|
99
|
-
| `projectRoot`
|
|
100
|
-
| `autoInstall`
|
|
101
|
-
| `packageManager`
|
|
102
|
-
| `registry`
|
|
103
|
-
| `debug`
|
|
104
|
-
| `aliasPrefix`
|
|
102
|
+
| 选项 | 类型 | 默认值 | 说明 |
|
|
103
|
+
| ------------------ | ------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
104
|
+
| `dependencies` | `string[]` | - | **必填**,需要分析的依赖包名列表 |
|
|
105
|
+
| `projectRoot` | `string` | `process.cwd()` | 项目根目录路径 |
|
|
106
|
+
| `autoInstall` | `boolean` | `true` | 是否自动安装缺失的别名依赖 |
|
|
107
|
+
| `packageManager` | `'auto' \| 'npm' \| 'yarn' \| 'pnpm'` | `'auto'` | 包管理器类型,`'auto'` 自动检测 |
|
|
108
|
+
| `registry` | `string` | 自动检测 | NPM 注册表地址,不指定则自动从 .npmrc 读取 |
|
|
109
|
+
| `debug` | `boolean` | `false` | 是否启用调试日志 |
|
|
110
|
+
| `aliasPrefix` | `string` | `'aliased-'` | 别名前缀 |
|
|
111
|
+
| `excludeRedirects` | `Record<string, string[]>` | `{}` | 从重定向列表中排除特定包。键为原始包名,值为要排除的 importer 包名列表。示例:`{ vue: ['vue-demi', 'pinia'] }` |
|
|
112
|
+
| `includeRedirects` | `Record<string, string[]>` | `{}` | 强制将指定包加入重定向列表,优先于 `excludeRedirects` 执行。适用于 semver 范围写得过宽(如 `>=2.5.0`)但运行时仍依赖旧版本的包。示例:`{ vue: ['@rili/ui', '@kmt/meeting-setting'] }` |
|
|
113
|
+
|
|
114
|
+
### Vite 插件专属选项
|
|
115
|
+
|
|
116
|
+
| 选项 | 类型 | 默认值 | 说明 |
|
|
117
|
+
| --------------- | --------- | ------ | ----------------------------- |
|
|
118
|
+
| `enableInDev` | `boolean` | `true` | 是否在开发模式(dev)下启用 |
|
|
119
|
+
| `enableInBuild` | `boolean` | `true` | 是否在构建模式(build)下启用 |
|
|
105
120
|
|
|
106
121
|
### 自动检测
|
|
107
122
|
|
|
@@ -169,6 +184,15 @@ import Vue from 'vue'; // → 解析到 aliased-vue2
|
|
|
169
184
|
import Vue from 'vue'; // → 解析到 vue (3.x)
|
|
170
185
|
```
|
|
171
186
|
|
|
187
|
+
### 行为边界
|
|
188
|
+
|
|
189
|
+
- **冲突检测范围**:只检测用户指定的 `dependencies` 的第一层 `peerDependencies` 与主工程的版本冲突。子依赖的 `peerDependencies` 不触发别名安装。
|
|
190
|
+
- **重定向范围**:声明冲突 peer 的包及其所有子依赖(`dependencies` + `peerDependencies` 递归)都会被收入重定向候选列表。冲突包自身(如 `vue`、`vue-router`)在收集时会被自动排除,避免主工程的同名引用被错误重定向。
|
|
191
|
+
- **`excludeRedirects`**:从重定向候选列表中剔除指定包,适用于运行时实际使用宿主 Vue 3 版本的共享包(如 `vue-demi`、`pinia`)。
|
|
192
|
+
- **`includeRedirects`**:将指定包强制加入重定向列表,适用于 semver 范围写得过宽(如 `vue: ">=2.5.0"` 同时满足 Vue 2/3),但运行时仍需要使用旧版本的包。`includeRedirects` 在 `excludeRedirects` 之前应用。
|
|
193
|
+
- **别名安装**:只为"主工程已声明且版本冲突"的依赖自动安装别名。未声明的 peer 依赖只会输出警告,不自动安装。
|
|
194
|
+
- **依赖图去重**:依赖树遍历按包名去重(同名包只分析一次)。在极少数情况下,如同一包名存在多个不同版本的嵌套安装,只有第一个被解析到的版本会被分析。这对重定向结果的影响极小,因为重定向判断只基于包名匹配,不涉及版本。
|
|
195
|
+
|
|
172
196
|
## 高级用法
|
|
173
197
|
|
|
174
198
|
### 钩子函数
|
|
@@ -178,12 +202,12 @@ depsConflictResolverVitePlugin({
|
|
|
178
202
|
dependencies: ['legacy-lib'],
|
|
179
203
|
hooks: {
|
|
180
204
|
// 分析完成后
|
|
181
|
-
onAnalysisComplete: result => {
|
|
205
|
+
onAnalysisComplete: (result) => {
|
|
182
206
|
console.log('Found conflicts:', result.peerConflicts);
|
|
183
207
|
},
|
|
184
208
|
|
|
185
209
|
// 安装完成后
|
|
186
|
-
onInstallComplete: installed => {
|
|
210
|
+
onInstallComplete: (installed) => {
|
|
187
211
|
console.log('Installed aliases:', installed);
|
|
188
212
|
},
|
|
189
213
|
|
|
@@ -199,6 +223,31 @@ depsConflictResolverVitePlugin({
|
|
|
199
223
|
});
|
|
200
224
|
```
|
|
201
225
|
|
|
226
|
+
### 精细控制重定向范围(includeRedirects + excludeRedirects)
|
|
227
|
+
|
|
228
|
+
当项目同时包含 Vue 2 依赖和 Vue 3 依赖时,自动检测可能无法准确区分。可以用这两个选项手动调节:
|
|
229
|
+
|
|
230
|
+
```typescript
|
|
231
|
+
new DepsConflictResolverWebpackPlugin({
|
|
232
|
+
dependencies: ['@uikit/vue-finder', '@rili/ui'],
|
|
233
|
+
|
|
234
|
+
// 强制将这些包(semver 范围过宽,但实际需要 Vue 2)加入重定向列表
|
|
235
|
+
includeRedirects: {
|
|
236
|
+
vue: ['@rili/ui', '@kmt/meeting-setting'],
|
|
237
|
+
},
|
|
238
|
+
|
|
239
|
+
// 从重定向列表中排除这些包(它们在运行时使用宿主提供的 Vue 3)
|
|
240
|
+
excludeRedirects: {
|
|
241
|
+
vue: ['vue-demi', 'pinia', '@ks-email/editor'],
|
|
242
|
+
},
|
|
243
|
+
|
|
244
|
+
aliasPrefix: 'never-ever-gonna-import-',
|
|
245
|
+
autoInstall: true,
|
|
246
|
+
});
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
规则优先级:`includeRedirects` 先执行,`excludeRedirects` 后执行。若同一个包同时出现在两者中,`excludeRedirects` 优先(最终不重定向)。
|
|
250
|
+
|
|
202
251
|
### 复用已有别名
|
|
203
252
|
|
|
204
253
|
如果项目中已经安装了合适版本的别名(如 `vue2@npm:vue@2.6.14`),插件会自动检测并复用,不会重复安装。
|
|
@@ -228,21 +277,39 @@ depsConflictResolverVitePlugin({
|
|
|
228
277
|
|
|
229
278
|
```bash
|
|
230
279
|
# 安装依赖
|
|
231
|
-
|
|
280
|
+
pnpm install
|
|
232
281
|
|
|
233
282
|
# 开发模式
|
|
234
|
-
|
|
283
|
+
pnpm dev
|
|
235
284
|
|
|
236
285
|
# 构建
|
|
237
|
-
|
|
286
|
+
pnpm build
|
|
238
287
|
|
|
239
288
|
# 运行测试
|
|
240
|
-
|
|
289
|
+
pnpm test
|
|
241
290
|
|
|
242
291
|
# 类型检查
|
|
243
|
-
|
|
292
|
+
pnpm typecheck
|
|
293
|
+
|
|
294
|
+
# 代码检查
|
|
295
|
+
pnpm lint
|
|
296
|
+
|
|
297
|
+
# 代码格式化
|
|
298
|
+
pnpm fmt
|
|
244
299
|
```
|
|
245
300
|
|
|
301
|
+
## 发布流程
|
|
302
|
+
|
|
303
|
+
本项目使用 [release-please](https://github.com/googleapis/release-please) 自动化发版:
|
|
304
|
+
|
|
305
|
+
1. 遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范提交代码到 `main` 分支
|
|
306
|
+
2. release-please 自动创建/更新 Release PR,包含版本号和 CHANGELOG
|
|
307
|
+
3. 审核并合并 Release PR
|
|
308
|
+
4. 自动创建 GitHub Release + tag
|
|
309
|
+
5. 手动执行 `npm publish` 发布到 npm
|
|
310
|
+
|
|
311
|
+
详见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
|
|
312
|
+
|
|
246
313
|
## 许可证
|
|
247
314
|
|
|
248
315
|
MIT
|
|
@@ -58,11 +58,11 @@ interface PeerConflict {
|
|
|
58
58
|
*/
|
|
59
59
|
conflictingRanges: DependencyPath[];
|
|
60
60
|
/**
|
|
61
|
-
*
|
|
61
|
+
* 是否存在版本范围不兼容(纯粹描述 peer 范围与已安装版本的兼容性,不考虑是否已声明)
|
|
62
62
|
*/
|
|
63
63
|
hasConflict: boolean;
|
|
64
64
|
/**
|
|
65
|
-
*
|
|
65
|
+
* 是否需要安装别名(= hasConflict + 主工程已声明且已安装该包)
|
|
66
66
|
*/
|
|
67
67
|
needsAlias: boolean;
|
|
68
68
|
}
|
|
@@ -106,10 +106,17 @@ interface AliasMapping {
|
|
|
106
106
|
usedBy: string[];
|
|
107
107
|
/**
|
|
108
108
|
* 所有需要重定向的依赖包名列表
|
|
109
|
-
* 包含 usedBy 中包的所有运行时子依赖(dependencies
|
|
109
|
+
* 包含 usedBy 中包的所有运行时子依赖(dependencies + peerDependencies 递归)
|
|
110
110
|
* 用于判断某个 importer 是否需要重定向到别名版本
|
|
111
|
+
* 注意:冲突包自身(如 vue、vue-router)已在收集时被排除,避免主工程引用被误重定向
|
|
111
112
|
*/
|
|
112
113
|
allDependents: string[];
|
|
114
|
+
/**
|
|
115
|
+
* Normalized installed package directories whose importers use this alias.
|
|
116
|
+
* When present, runtime matching is scoped to these package instances and
|
|
117
|
+
* does not fall back to the legacy name-only `allDependents` rule.
|
|
118
|
+
*/
|
|
119
|
+
importerPaths?: string[];
|
|
113
120
|
}
|
|
114
121
|
/**
|
|
115
122
|
* 依赖分析结果
|
|
@@ -128,7 +135,7 @@ interface AnalysisResult {
|
|
|
128
135
|
*/
|
|
129
136
|
aliasMappings: AliasMapping[];
|
|
130
137
|
/**
|
|
131
|
-
* 第一层依赖中缺失的 peer
|
|
138
|
+
* 第一层依赖中缺失的 peer 依赖(不自动安装,仅警告提示用户)
|
|
132
139
|
*/
|
|
133
140
|
missingFirstLevelPeers: Array<{
|
|
134
141
|
packageName: string;
|
|
@@ -192,10 +199,19 @@ interface DepsConflictResolverOptions {
|
|
|
192
199
|
aliasPrefix?: string;
|
|
193
200
|
/**
|
|
194
201
|
* 排除特定依赖包对某些模块的解析重定向
|
|
195
|
-
*
|
|
202
|
+
* 键为原始包名,值为需要从 allDependents 中剔除的包名列表
|
|
196
203
|
* @example { vue: ['vue-demi'] } - vue-demi 中的 import vue 不会被重定向
|
|
197
204
|
*/
|
|
198
205
|
excludeRedirects?: Record<string, string[]>;
|
|
206
|
+
/**
|
|
207
|
+
* 显式纳入特定依赖包对某些模块的解析重定向
|
|
208
|
+
* 键为原始包名,值为需要强制加入 allDependents 的包名列表
|
|
209
|
+
* 常用于处理 semver 范围写得过宽(如 ">=2.5.0" 同时满足 Vue 2/3),
|
|
210
|
+
* 但运行时仍依赖旧版本实现的包
|
|
211
|
+
* 优先于 excludeRedirects 应用(include 后再 exclude)
|
|
212
|
+
* @example { vue: ['@rili/ui', '@kmt/meeting-setting'] }
|
|
213
|
+
*/
|
|
214
|
+
includeRedirects?: Record<string, string[]>;
|
|
199
215
|
}
|
|
200
216
|
/**
|
|
201
217
|
* 解析后的配置(带默认值)
|
|
@@ -58,11 +58,11 @@ interface PeerConflict {
|
|
|
58
58
|
*/
|
|
59
59
|
conflictingRanges: DependencyPath[];
|
|
60
60
|
/**
|
|
61
|
-
*
|
|
61
|
+
* 是否存在版本范围不兼容(纯粹描述 peer 范围与已安装版本的兼容性,不考虑是否已声明)
|
|
62
62
|
*/
|
|
63
63
|
hasConflict: boolean;
|
|
64
64
|
/**
|
|
65
|
-
*
|
|
65
|
+
* 是否需要安装别名(= hasConflict + 主工程已声明且已安装该包)
|
|
66
66
|
*/
|
|
67
67
|
needsAlias: boolean;
|
|
68
68
|
}
|
|
@@ -106,10 +106,17 @@ interface AliasMapping {
|
|
|
106
106
|
usedBy: string[];
|
|
107
107
|
/**
|
|
108
108
|
* 所有需要重定向的依赖包名列表
|
|
109
|
-
* 包含 usedBy 中包的所有运行时子依赖(dependencies
|
|
109
|
+
* 包含 usedBy 中包的所有运行时子依赖(dependencies + peerDependencies 递归)
|
|
110
110
|
* 用于判断某个 importer 是否需要重定向到别名版本
|
|
111
|
+
* 注意:冲突包自身(如 vue、vue-router)已在收集时被排除,避免主工程引用被误重定向
|
|
111
112
|
*/
|
|
112
113
|
allDependents: string[];
|
|
114
|
+
/**
|
|
115
|
+
* Normalized installed package directories whose importers use this alias.
|
|
116
|
+
* When present, runtime matching is scoped to these package instances and
|
|
117
|
+
* does not fall back to the legacy name-only `allDependents` rule.
|
|
118
|
+
*/
|
|
119
|
+
importerPaths?: string[];
|
|
113
120
|
}
|
|
114
121
|
/**
|
|
115
122
|
* 依赖分析结果
|
|
@@ -128,7 +135,7 @@ interface AnalysisResult {
|
|
|
128
135
|
*/
|
|
129
136
|
aliasMappings: AliasMapping[];
|
|
130
137
|
/**
|
|
131
|
-
* 第一层依赖中缺失的 peer
|
|
138
|
+
* 第一层依赖中缺失的 peer 依赖(不自动安装,仅警告提示用户)
|
|
132
139
|
*/
|
|
133
140
|
missingFirstLevelPeers: Array<{
|
|
134
141
|
packageName: string;
|
|
@@ -192,10 +199,19 @@ interface DepsConflictResolverOptions {
|
|
|
192
199
|
aliasPrefix?: string;
|
|
193
200
|
/**
|
|
194
201
|
* 排除特定依赖包对某些模块的解析重定向
|
|
195
|
-
*
|
|
202
|
+
* 键为原始包名,值为需要从 allDependents 中剔除的包名列表
|
|
196
203
|
* @example { vue: ['vue-demi'] } - vue-demi 中的 import vue 不会被重定向
|
|
197
204
|
*/
|
|
198
205
|
excludeRedirects?: Record<string, string[]>;
|
|
206
|
+
/**
|
|
207
|
+
* 显式纳入特定依赖包对某些模块的解析重定向
|
|
208
|
+
* 键为原始包名,值为需要强制加入 allDependents 的包名列表
|
|
209
|
+
* 常用于处理 semver 范围写得过宽(如 ">=2.5.0" 同时满足 Vue 2/3),
|
|
210
|
+
* 但运行时仍依赖旧版本实现的包
|
|
211
|
+
* 优先于 excludeRedirects 应用(include 后再 exclude)
|
|
212
|
+
* @example { vue: ['@rili/ui', '@kmt/meeting-setting'] }
|
|
213
|
+
*/
|
|
214
|
+
includeRedirects?: Record<string, string[]>;
|
|
199
215
|
}
|
|
200
216
|
/**
|
|
201
217
|
* 解析后的配置(带默认值)
|