Dependency Matching Mechanism

comp-hub uses intelligent dependency matching to allow components to adapt to different local environments.

Why Dependency Matching is Needed

When components are previewed locally, they need to load dependencies already installed in the local project. But the reality is often:

• Component depends on echarts 5.2.0
• Locally installed is echarts 5.0.0

If strict version consistency is required, many components will not be able to preview normally. Therefore, the platform provides flexible dependency matching rules.

Matching Rules

In "Settings > Dependency Settings", you can configure matching rules for each dependency library:

Rule	Description	Applicable Scenario
Installed Only	As long as the dependency is installed locally, regardless of version	Quick preview, non-production environment
Major Version	Major version number must match	Recommended, balances compatibility and stability
Major.Minor Version	Both major and minor version numbers must match	Scenarios sensitive to versions
Exact Match	Version number must be exactly the same	Strict version control

Example

Assuming the component depends on echarts: 5.2.3:

Local Version	Installed Only	Major Version	Major.Minor	Exact Match
5.0.0	✅ Use	✅ Use	❌ Skip	❌ Skip
5.2.0	✅ Use	✅ Use	❌ Skip	❌ Skip
5.2.3	✅ Use	✅ Use	✅ Use	✅ Use
6.0.0	✅ Use	❌ Skip	❌ Skip	❌ Skip

Default Behavior

• Dependencies without configured rules default to Major Version matching
• Vue framework enforces Major Version matching (Vue 2 components will not attempt to run in Vue 3 projects)

Troubleshooting Component Not Displaying

When you can't see a component in the "Recommended" list, it may be due to dependency mismatch. Follow these steps to troubleshoot:

1. Switch to "All" Filter

Switch the filter condition at the top of the component market to "All" to see if the component is displayed.

2. Check Dependency Status

Click on the component card and check the dependency matching status on the preview page:

• 🟢 Green: Dependency matched successfully
• 🔴 Red: Dependency mismatch or missing
• ⚠️ Yellow: Dependency version has differences but can try to run

3. Install Missing Dependencies

If prompted that dependencies are missing, install them in the local project:

npm install <package-name>

Refresh the page after installation.

4. Adjust Matching Rules

If dependency versions differ but do not affect functionality, you can relax the matching rules in "Dependency Settings".

Best Practices

Component Authors

• Clearly state dependency requirements in README.md
• Use dependency versions with good compatibility as much as possible
• Avoid relying on specific minor version features

Component Users

• Keep local dependency versions relatively new to improve component compatibility
• For non-critical dependencies, you can use "Installed Only" or "Major Version" matching
• When encountering issues, prioritize checking console error messages

FAQ

Q: Why does the component prompt "Missing dependency" but it's already installed locally?

A: Possible reasons:

1. Dependency name spelling inconsistency (e.g., echarts vs ECharts)
2. Dependency is installed in a subdirectory's node_modules
3. Need to refresh the page to re-detect

Q: Can I force a component with mismatched dependencies to run?

A: You can view the component in the "All" list, but whether it runs normally depends on the actual API differences. It is recommended to resolve dependency issues first.

Q: Do matching rules apply to downloaded components?

A: Matching rules only affect online preview. Downloaded components run in your project using your project's dependency versions.