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 → Preview Rule", the Dependencies section lets you configure a matching rule for every dependency in your project (both dependencies and devDependencies):

Rule	Description	Applicable Scenario	Color Indicator
Auto	No version restriction, renders with the current local environment	Default, keeps everything renderable	⚪ Grey (Default)
Installed Only	The dependency only needs to be installed locally, regardless of version	Quick preview, non-production environment	🟢 Green (Most Lenient)
Major Version	Major version number must match	Balances compatibility and stability	🔵 Blue
Major.Minor Version	Both major and minor version numbers must match	Scenarios sensitive to versions	🟠 Orange (Moderately Strict)
Exact Match	Version number must be exactly the same	Strict version control	🔴 Red (Most Strict)

The rules are read from your project's package.json and are also used when pre-building dependencies for preview.

Tip: Each matching rule in the settings page has a corresponding colored dot indicator in front of it, making it easy to quickly identify the matching strictness level.

Example

Assuming the component depends on echarts: 5.2.3:

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

Default Behavior

• Dependencies without a manually configured rule default to Auto (no version restriction, render with the current local environment)
• A dependency that is not installed locally at all is never matched — install it and refresh
• Framework is detected from the component's own dependencies: a component importing vue renders as Vue, one importing react renders as React (React 17 and 18 are both supported); a component importing both cannot be rendered

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 "Settings → Preview Rule".

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.