mirror of
https://github.com/johndoe6345789/low-code-react-app-b.git
synced 2026-04-25 06:04:54 +00:00
114 lines
2.7 KiB
Markdown
114 lines
2.7 KiB
Markdown
# Dependency Management Guide
|
|
|
|
## Overview
|
|
|
|
This project uses npm workspaces with custom overrides configuration to manage dependencies without requiring `--legacy-peer-deps`.
|
|
|
|
## Key Changes
|
|
|
|
### 1. Workspace Protocol Replacement
|
|
|
|
**Before:**
|
|
```json
|
|
"@github/spark": "workspace:*"
|
|
```
|
|
|
|
**After:**
|
|
```json
|
|
"@github/spark": "file:./packages/spark-tools"
|
|
```
|
|
|
|
**Why:** The `workspace:*` protocol is not supported by standard npm in CI/CD environments. Using `file:` protocol ensures compatibility across all npm versions and build contexts.
|
|
|
|
### 2. Dependency Overrides
|
|
|
|
The `overrides` field forces consistent versions across all dependencies, eliminating peer dependency conflicts:
|
|
|
|
```json
|
|
"overrides": {
|
|
"react": "^19.0.0",
|
|
"react-dom": "^19.0.0",
|
|
"@types/react": "^19.0.10",
|
|
"@types/react-dom": "^19.0.4",
|
|
"vite": "^7.3.1",
|
|
"@github/spark": {
|
|
"react": "^19.0.0",
|
|
"vite": "^7.3.1"
|
|
},
|
|
"@local/spark-wrapper": {
|
|
"react": "^19.0.0"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Benefits
|
|
|
|
1. **No More `--legacy-peer-deps`**: Overrides resolve peer dependency conflicts automatically
|
|
2. **CI/CD Compatible**: Works with standard `npm ci` in GitHub Actions and other CI systems
|
|
3. **Version Consistency**: Ensures all packages use the same React and Vite versions
|
|
4. **Monorepo Support**: Maintains workspace functionality while improving compatibility
|
|
|
|
## Installation
|
|
|
|
### Local Development
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
### CI/CD
|
|
```bash
|
|
npm ci
|
|
```
|
|
|
|
Both commands now work without additional flags.
|
|
|
|
## Troubleshooting
|
|
|
|
### Lock File Out of Sync
|
|
|
|
If you see "lock file out of sync" errors in CI:
|
|
|
|
```bash
|
|
# Locally run:
|
|
npm install
|
|
|
|
# Commit the updated package-lock.json:
|
|
git add package-lock.json
|
|
git commit -m "Update lock file"
|
|
git push
|
|
```
|
|
|
|
### Peer Dependency Warnings
|
|
|
|
If you still see peer dependency warnings:
|
|
|
|
1. Check that the override versions match your main dependency versions
|
|
2. Update the override to match the required version
|
|
3. Run `npm install` to regenerate the lock file
|
|
|
|
### Workspace Package Not Found
|
|
|
|
If the workspace package isn't found:
|
|
|
|
1. Verify the path in the `file:` reference is correct
|
|
2. Ensure the workspace package has a valid `package.json`
|
|
3. Run `npm install` to rebuild workspace links
|
|
|
|
## Architecture
|
|
|
|
```
|
|
spark-template/
|
|
├── package.json (root with overrides)
|
|
├── packages/
|
|
│ ├── spark/ (@local/spark-wrapper)
|
|
│ └── spark-tools/ (@github/spark)
|
|
└── node_modules/
|
|
└── @github/spark → ../packages/spark-tools
|
|
```
|
|
|
|
## References
|
|
|
|
- [npm overrides documentation](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#overrides)
|
|
- [npm workspaces documentation](https://docs.npmjs.com/cli/v10/using-npm/workspaces)
|
|
- [file: protocol specification](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#local-paths)
|