deps-conflict-resolver 1.1.0 → 1.1.2
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 +321 -0
- package/README.md +62 -32
- package/dist/{config.types-FhZrFXHQ.d.cts → config.types-DPfKh8_B.d.cts} +6 -0
- package/dist/{config.types-FhZrFXHQ.d.ts → config.types-DPfKh8_B.d.ts} +6 -0
- package/dist/index.cjs +1333 -231
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +1335 -233
- package/dist/index.js.map +1 -1
- package/dist/{resolver-BG2AVCds.d.cts → resolver-BBrA-8me.d.ts} +31 -1
- package/dist/{resolver-z_muBpc_.d.ts → resolver-Bres_MgX.d.cts} +31 -1
- package/dist/vite.cjs +1350 -251
- 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 +1352 -253
- package/dist/vite.js.map +1 -1
- package/dist/webpack.cjs +1440 -267
- 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 +1442 -269
- package/dist/webpack.js.map +1 -1
- package/package.json +73 -48
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,321 @@
|
|
|
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, while preserving nested instances by their installed paths
|
|
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; an explicit value is used for both version queries and alias installation |
|
|
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. User-level `.pnpmrc` for pnpm or `.yarnrc.yml` in yarn projects
|
|
136
|
+
4. Falls back to `https://registry.npmjs.org`
|
|
137
|
+
|
|
138
|
+
An explicit `registry` option overrides this detection. The resolver uses it for remote version queries, and the package manager uses the same registry when installing aliases.
|
|
139
|
+
|
|
140
|
+
## How It Works
|
|
141
|
+
|
|
142
|
+
### 1. Dependency Analysis
|
|
143
|
+
|
|
144
|
+
The plugin recursively analyzes the entire dependency tree of the specified packages:
|
|
145
|
+
|
|
146
|
+
```
|
|
147
|
+
package-a
|
|
148
|
+
├── package-b
|
|
149
|
+
│ └── package-c (peerDeps: vue@^2.0.0)
|
|
150
|
+
└── package-d (peerDeps: vue-router@^3.0.0)
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
### 2. Conflict Detection
|
|
154
|
+
|
|
155
|
+
Compares installed versions in the host project against peer dependency requirements:
|
|
156
|
+
|
|
157
|
+
- Host project: `vue@3.2.0`, `vue-router@4.1.0`
|
|
158
|
+
- Peer dependency requirements: `vue@^2.0.0`, `vue-router@^3.0.0`
|
|
159
|
+
- Conflict detected ✗
|
|
160
|
+
|
|
161
|
+
### 3. Version Resolution
|
|
162
|
+
|
|
163
|
+
Before making a remote request, the resolver checks installed local and workspace npm aliases whose package identity and version satisfy the conflicting range. A matching alias is reused offline with no registry access or reinstall; only unresolved requests query the registry and select the best version that satisfies all peer dependency ranges:
|
|
164
|
+
|
|
165
|
+
- `vue@^2.0.0` → selects `vue@2.7.14`
|
|
166
|
+
- `vue-router@^3.0.0` → selects `vue-router@3.6.5`
|
|
167
|
+
|
|
168
|
+
### 4. Alias Installation
|
|
169
|
+
|
|
170
|
+
Creates and installs aliased dependencies:
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
npm install aliased-vue2@npm:vue@2.7.14
|
|
174
|
+
npm install aliased-vue-router3@npm:vue-router@3.6.5
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
### 5. Module Resolution Redirection
|
|
178
|
+
|
|
179
|
+
At build time, module imports are automatically redirected:
|
|
180
|
+
|
|
181
|
+
```javascript
|
|
182
|
+
// Inside package-c
|
|
183
|
+
import Vue from 'vue'; // → resolves to aliased-vue2
|
|
184
|
+
|
|
185
|
+
// In the host project
|
|
186
|
+
import Vue from 'vue'; // → resolves to vue (3.x)
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
### Behavioral Boundaries
|
|
190
|
+
|
|
191
|
+
- **Conflict Detection Scope**: Only the first-level `peerDependencies` of user-specified `dependencies` are checked for version conflicts against the host project. Sub-dependency `peerDependencies` still contribute to graph construction and runtime redirect matching, but do not independently trigger alias installation. First-level peers marked `optional: true` are skipped entirely: they produce no conflict, missing-peer warning, or alias.
|
|
192
|
+
- **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.
|
|
193
|
+
- **Nested Versions**: The installed dependency graph is keyed by normalized package directories, and each child is resolved relative to its owning package. Nested instances with the same name but different versions remain distinct; generated redirect rules prefer importer-path matching. Consequently, `excludeRedirects` applies to concrete package instances and their subtrees rather than globally deduplicating by name.
|
|
194
|
+
- **`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.
|
|
195
|
+
- **`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`.
|
|
196
|
+
- **Alias Installation and Reuse**: 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. A matching installed local or workspace alias is reused without registry access or installation; a declared but uninstalled workspace alias is not reusable. If an existing alias directory has the wrong identity or version, the resolver reports a collision and leaves that directory unchanged rather than replacing it.
|
|
197
|
+
- **Registry**: An explicit `registry` value controls both remote version resolution and package-manager alias installation; automatic detection is used only when it is omitted.
|
|
198
|
+
- **Initialization Failure Policy**: `createResolver()` and the Vite plugin propagate initialization failures to the caller. The Webpack plugin remains fail-open: initialization or module-resolution errors are logged and compilation continues without aliases for that generation. Each Webpack `watchRun` invalidates the previous generation, waits for a fresh analysis, and can retry on the next watch cycle if initialization fails.
|
|
199
|
+
|
|
200
|
+
## Advanced Usage
|
|
201
|
+
|
|
202
|
+
### Hooks
|
|
203
|
+
|
|
204
|
+
```typescript
|
|
205
|
+
depsConflictResolverVitePlugin({
|
|
206
|
+
dependencies: ['legacy-lib'],
|
|
207
|
+
hooks: {
|
|
208
|
+
// After analysis completes
|
|
209
|
+
onAnalysisComplete: (result) => {
|
|
210
|
+
console.log('Found conflicts:', result.peerConflicts);
|
|
211
|
+
},
|
|
212
|
+
|
|
213
|
+
// After the installation attempt completes
|
|
214
|
+
onInstallComplete: (mappings) => {
|
|
215
|
+
console.log('Alias mappings after install attempt:', mappings);
|
|
216
|
+
},
|
|
217
|
+
|
|
218
|
+
// Custom module resolution
|
|
219
|
+
beforeResolve: (source, importer) => {
|
|
220
|
+
// Return a new module name, or null to skip
|
|
221
|
+
if (source === 'special-module') {
|
|
222
|
+
return 'custom-alias';
|
|
223
|
+
}
|
|
224
|
+
return null;
|
|
225
|
+
},
|
|
226
|
+
},
|
|
227
|
+
});
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
`onInstallComplete` runs after the installation attempt; its argument is the alias mappings produced by that analysis and does not guarantee that every mapping was installed successfully (reused, installed, and failed outcomes must be checked in logs or installation results).
|
|
231
|
+
|
|
232
|
+
### Fine-Grained Redirect Control (includeRedirects + excludeRedirects)
|
|
233
|
+
|
|
234
|
+
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:
|
|
235
|
+
|
|
236
|
+
```typescript
|
|
237
|
+
new DepsConflictResolverWebpackPlugin({
|
|
238
|
+
dependencies: ['@uikit/vue-finder', '@rili/ui'],
|
|
239
|
+
|
|
240
|
+
// Force these packages (broad semver range, but actually need Vue 2) into the redirect list
|
|
241
|
+
includeRedirects: {
|
|
242
|
+
vue: ['@rili/ui', '@kmt/meeting-setting'],
|
|
243
|
+
},
|
|
244
|
+
|
|
245
|
+
// Exclude these packages from the redirect list (they use the host's Vue 3 at runtime)
|
|
246
|
+
excludeRedirects: {
|
|
247
|
+
vue: ['vue-demi', 'pinia', '@ks-email/editor'],
|
|
248
|
+
},
|
|
249
|
+
|
|
250
|
+
aliasPrefix: 'never-ever-gonna-import-',
|
|
251
|
+
autoInstall: true,
|
|
252
|
+
});
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
Priority: `includeRedirects` is applied first, then `excludeRedirects`. If the same package appears in both, `excludeRedirects` wins (not redirected).
|
|
256
|
+
|
|
257
|
+
### Reusing Existing Aliases
|
|
258
|
+
|
|
259
|
+
If the project already has aliases installed with suitable versions (e.g., `vue2@npm:vue@2.6.14`), the plugin detects and reuses them before contacting the registry, without reinstalling. Workspace aliases are reusable only when actually installed and when package identity/version validation succeeds. A mismatched existing directory is reported as a collision and left unchanged.
|
|
260
|
+
|
|
261
|
+
## API Reference
|
|
262
|
+
|
|
263
|
+
### `createResolver(options): Promise<DepsConflictResolver>`
|
|
264
|
+
|
|
265
|
+
Creates and initializes a dependency resolver.
|
|
266
|
+
|
|
267
|
+
### `DepsConflictResolver`
|
|
268
|
+
|
|
269
|
+
Main resolver class:
|
|
270
|
+
|
|
271
|
+
- `initialize(): Promise<void>` — Initialize the resolver
|
|
272
|
+
- `resolveModule(request, importer): string | null` — Resolve a module
|
|
273
|
+
- `getAnalysisResult(): AnalysisResult` — Get the analysis result
|
|
274
|
+
- `getAliasPathMappings(): AliasPathMapping[]` — Get generic alias path mappings
|
|
275
|
+
|
|
276
|
+
> The core module returns a generic `AliasPathMapping[]` format, which each build tool plugin (Webpack/Vite) converts to its own alias configuration format.
|
|
277
|
+
|
|
278
|
+
### Utility Functions
|
|
279
|
+
|
|
280
|
+
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.
|
|
281
|
+
|
|
282
|
+
## Development
|
|
283
|
+
|
|
284
|
+
```bash
|
|
285
|
+
# Install dependencies
|
|
286
|
+
pnpm install
|
|
287
|
+
|
|
288
|
+
# Development mode
|
|
289
|
+
pnpm dev
|
|
290
|
+
|
|
291
|
+
# Build
|
|
292
|
+
pnpm build
|
|
293
|
+
|
|
294
|
+
# Run tests
|
|
295
|
+
pnpm test
|
|
296
|
+
|
|
297
|
+
# Type checking
|
|
298
|
+
pnpm typecheck
|
|
299
|
+
|
|
300
|
+
# Lint
|
|
301
|
+
pnpm lint
|
|
302
|
+
|
|
303
|
+
# Format
|
|
304
|
+
pnpm fmt
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
## Release Process
|
|
308
|
+
|
|
309
|
+
This project uses [release-please](https://github.com/googleapis/release-please) for automated releases:
|
|
310
|
+
|
|
311
|
+
1. Merge commits to `main` following [Conventional Commits](https://www.conventionalcommits.org/)
|
|
312
|
+
2. release-please automatically creates/updates a Release PR with changelog
|
|
313
|
+
3. Review and merge the Release PR
|
|
314
|
+
4. A GitHub Release + tag is automatically created
|
|
315
|
+
5. Manually run `npm publish` to publish to npm
|
|
316
|
+
|
|
317
|
+
See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
|
|
318
|
+
|
|
319
|
+
## License
|
|
320
|
+
|
|
321
|
+
MIT
|
package/README.md
CHANGED
|
@@ -1,10 +1,16 @@
|
|
|
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
|
## 功能特性
|
|
6
12
|
|
|
7
|
-
- 🔍
|
|
13
|
+
- 🔍 **递归依赖分析**:深度遍历依赖树中的所有子依赖、孙依赖,并按实际安装路径区分嵌套实例
|
|
8
14
|
- 🎯 **智能冲突检测**:自动识别 peer 依赖与主工程的版本冲突
|
|
9
15
|
- 📦 **自动别名安装**:为冲突的依赖创建别名并自动安装合适的版本
|
|
10
16
|
- 🔄 **模块解析重定向**:在运行时自动将模块引用重定向到正确的别名版本
|
|
@@ -93,24 +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`
|
|
105
|
-
| `excludeRedirects`
|
|
106
|
-
| `includeRedirects`
|
|
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 注册表地址;显式指定时同时用于版本查询和别名安装 |
|
|
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'] }` |
|
|
107
113
|
|
|
108
114
|
### Vite 插件专属选项
|
|
109
115
|
|
|
110
|
-
| 选项 | 类型 | 默认值
|
|
111
|
-
| --------------- | --------- |
|
|
112
|
-
| `enableInDev` | `boolean` | `true`
|
|
113
|
-
| `enableInBuild` | `boolean` | `true`
|
|
116
|
+
| 选项 | 类型 | 默认值 | 说明 |
|
|
117
|
+
| --------------- | --------- | ------ | ----------------------------- |
|
|
118
|
+
| `enableInDev` | `boolean` | `true` | 是否在开发模式(dev)下启用 |
|
|
119
|
+
| `enableInBuild` | `boolean` | `true` | 是否在构建模式(build)下启用 |
|
|
114
120
|
|
|
115
121
|
### 自动检测
|
|
116
122
|
|
|
@@ -126,9 +132,11 @@ const resolved = resolver.resolveModule('vue', '/path/to/importer.js');
|
|
|
126
132
|
|
|
127
133
|
1. 项目级 `.npmrc` 文件
|
|
128
134
|
2. 用户级 `~/.npmrc` 文件
|
|
129
|
-
3. yarn 项目的 `.yarnrc.yml` 文件
|
|
135
|
+
3. pnpm 的用户级 `.pnpmrc` 或 yarn 项目的 `.yarnrc.yml` 文件
|
|
130
136
|
4. 默认使用 `https://registry.npmjs.org`
|
|
131
137
|
|
|
138
|
+
显式设置 `registry` 时会覆盖上述自动检测结果:解析器从该地址查询可用版本,包管理器安装别名时也使用同一地址。
|
|
139
|
+
|
|
132
140
|
## 工作原理
|
|
133
141
|
|
|
134
142
|
### 1. 依赖分析
|
|
@@ -152,7 +160,7 @@ package-a
|
|
|
152
160
|
|
|
153
161
|
### 3. 版本解析
|
|
154
162
|
|
|
155
|
-
|
|
163
|
+
先检查项目或 workspace 中已经安装、且包名和版本都匹配的 npm alias。可复用的 alias 会直接离线使用,不访问 registry,也不会重复安装;只有未匹配的请求才从 registry 获取版本列表,并找到满足所有 peer 依赖范围的最佳版本:
|
|
156
164
|
|
|
157
165
|
- `vue@^2.0.0` → 选择 `vue@2.7.14`
|
|
158
166
|
- `vue-router@^3.0.0` → 选择 `vue-router@3.6.5`
|
|
@@ -180,12 +188,14 @@ import Vue from 'vue'; // → 解析到 vue (3.x)
|
|
|
180
188
|
|
|
181
189
|
### 行为边界
|
|
182
190
|
|
|
183
|
-
- **冲突检测范围**:只检测用户指定的 `dependencies` 的第一层 `peerDependencies` 与主工程的版本冲突。子依赖的 `peerDependencies`
|
|
184
|
-
-
|
|
191
|
+
- **冲突检测范围**:只检测用户指定的 `dependencies` 的第一层 `peerDependencies` 与主工程的版本冲突。子依赖的 `peerDependencies` 会参与依赖图构建和运行时重定向判断,但不会单独触发别名安装。标记为 `optional: true` 的第一层 peer 会完全跳过,不产生冲突、missing 警告或 alias。
|
|
192
|
+
- **重定向范围**:冲突 peer 的声明包及其 `dependencies`/`peerDependencies` 会递归加入重定向候选列表;冲突目标包自身(如 `vue`、`vue-router`)会被排除,避免主工程引用被误重定向。
|
|
193
|
+
- **嵌套版本**:依赖图以规范化的实际安装目录为节点,并从所属包目录解析子依赖。同名但不同版本的嵌套实例会保留为不同节点,生成的重定向规则优先按 importer 路径匹配;因此 `excludeRedirects` 也会作用于具体实例及其子树,而不是简单按包名全局去重。
|
|
185
194
|
- **`excludeRedirects`**:从重定向候选列表中剔除指定包,适用于运行时实际使用宿主 Vue 3 版本的共享包(如 `vue-demi`、`pinia`)。
|
|
186
195
|
- **`includeRedirects`**:将指定包强制加入重定向列表,适用于 semver 范围写得过宽(如 `vue: ">=2.5.0"` 同时满足 Vue 2/3),但运行时仍需要使用旧版本的包。`includeRedirects` 在 `excludeRedirects` 之前应用。
|
|
187
|
-
-
|
|
188
|
-
-
|
|
196
|
+
- **别名安装与复用**:只为“主工程已声明且版本冲突”的依赖自动安装别名;未声明的 peer 依赖只输出警告,不自动安装。已安装且身份/版本匹配的 local 或 workspace alias 会复用(无需 registry 和安装);声明但尚未安装的 workspace alias 不算可复用。已有目录身份或版本不匹配时会报告 alias collision,并保持原目录不变,不原地覆盖。
|
|
197
|
+
- **Registry**:`registry` 显式配置同时约束远程版本查询和包管理器安装;未配置时才按项目/用户配置自动检测。
|
|
198
|
+
- **初始化失败策略**:核心 `createResolver()` 与 Vite 插件会把初始化错误交给调用方;Webpack 插件保持 fail-open,初始化或模块解析失败只记录错误并继续编译(该轮不会应用 alias)。Webpack watch 每次 `watchRun` 会先失效旧 generation,再等待新分析;新一轮失败时仍可在后续 watch 周期重试。
|
|
189
199
|
|
|
190
200
|
## 高级用法
|
|
191
201
|
|
|
@@ -196,13 +206,13 @@ depsConflictResolverVitePlugin({
|
|
|
196
206
|
dependencies: ['legacy-lib'],
|
|
197
207
|
hooks: {
|
|
198
208
|
// 分析完成后
|
|
199
|
-
onAnalysisComplete: result => {
|
|
209
|
+
onAnalysisComplete: (result) => {
|
|
200
210
|
console.log('Found conflicts:', result.peerConflicts);
|
|
201
211
|
},
|
|
202
212
|
|
|
203
|
-
//
|
|
204
|
-
onInstallComplete:
|
|
205
|
-
console.log('
|
|
213
|
+
// 安装尝试完成后
|
|
214
|
+
onInstallComplete: (mappings) => {
|
|
215
|
+
console.log('Alias mappings after install attempt:', mappings);
|
|
206
216
|
},
|
|
207
217
|
|
|
208
218
|
// 自定义模块解析
|
|
@@ -217,6 +227,8 @@ depsConflictResolverVitePlugin({
|
|
|
217
227
|
});
|
|
218
228
|
```
|
|
219
229
|
|
|
230
|
+
`onInstallComplete` 在安装尝试结束后触发;其参数是本轮分析得到的 alias mappings,并不表示每个 mapping 都已成功安装(已复用、已安装和失败项需结合日志或安装结果判断)。
|
|
231
|
+
|
|
220
232
|
### 精细控制重定向范围(includeRedirects + excludeRedirects)
|
|
221
233
|
|
|
222
234
|
当项目同时包含 Vue 2 依赖和 Vue 3 依赖时,自动检测可能无法准确区分。可以用这两个选项手动调节:
|
|
@@ -244,7 +256,7 @@ new DepsConflictResolverWebpackPlugin({
|
|
|
244
256
|
|
|
245
257
|
### 复用已有别名
|
|
246
258
|
|
|
247
|
-
如果项目中已经安装了合适版本的别名(如 `vue2@npm:vue@2.6.14
|
|
259
|
+
如果项目中已经安装了合适版本的别名(如 `vue2@npm:vue@2.6.14`),插件会在访问 registry 前自动检测并复用,不会重复安装;workspace alias 只有在实际安装且包名/版本验证通过时才会复用。若现有目录不匹配,插件会报告冲突并保留原目录。
|
|
248
260
|
|
|
249
261
|
## API 参考
|
|
250
262
|
|
|
@@ -271,21 +283,39 @@ new DepsConflictResolverWebpackPlugin({
|
|
|
271
283
|
|
|
272
284
|
```bash
|
|
273
285
|
# 安装依赖
|
|
274
|
-
|
|
286
|
+
pnpm install
|
|
275
287
|
|
|
276
288
|
# 开发模式
|
|
277
|
-
|
|
289
|
+
pnpm dev
|
|
278
290
|
|
|
279
291
|
# 构建
|
|
280
|
-
|
|
292
|
+
pnpm build
|
|
281
293
|
|
|
282
294
|
# 运行测试
|
|
283
|
-
|
|
295
|
+
pnpm test
|
|
284
296
|
|
|
285
297
|
# 类型检查
|
|
286
|
-
|
|
298
|
+
pnpm typecheck
|
|
299
|
+
|
|
300
|
+
# 代码检查
|
|
301
|
+
pnpm lint
|
|
302
|
+
|
|
303
|
+
# 代码格式化
|
|
304
|
+
pnpm fmt
|
|
287
305
|
```
|
|
288
306
|
|
|
307
|
+
## 发布流程
|
|
308
|
+
|
|
309
|
+
本项目使用 [release-please](https://github.com/googleapis/release-please) 自动化发版:
|
|
310
|
+
|
|
311
|
+
1. 遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范提交代码到 `main` 分支
|
|
312
|
+
2. release-please 自动创建/更新 Release PR,包含版本号和 CHANGELOG
|
|
313
|
+
3. 审核并合并 Release PR
|
|
314
|
+
4. 自动创建 GitHub Release + tag
|
|
315
|
+
5. 手动执行 `npm publish` 发布到 npm
|
|
316
|
+
|
|
317
|
+
详见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
|
|
318
|
+
|
|
289
319
|
## 许可证
|
|
290
320
|
|
|
291
321
|
MIT
|
|
@@ -111,6 +111,12 @@ interface AliasMapping {
|
|
|
111
111
|
* 注意:冲突包自身(如 vue、vue-router)已在收集时被排除,避免主工程引用被误重定向
|
|
112
112
|
*/
|
|
113
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[];
|
|
114
120
|
}
|
|
115
121
|
/**
|
|
116
122
|
* 依赖分析结果
|
|
@@ -111,6 +111,12 @@ interface AliasMapping {
|
|
|
111
111
|
* 注意:冲突包自身(如 vue、vue-router)已在收集时被排除,避免主工程引用被误重定向
|
|
112
112
|
*/
|
|
113
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[];
|
|
114
120
|
}
|
|
115
121
|
/**
|
|
116
122
|
* 依赖分析结果
|