FAQ & Glossary
Startup and local service
The port is taken / changing the port has no effect
-p only applies while the master is not running. Run comphub kill first, then comphub -p 8080.
The comphub command does not exist
Use npx comp-hub, or install it globally and reopen the terminal: npm install comp-hub@latest -g.
Startup says an upgrade is required
Run npm install comp-hub@latest -g, then start again.
The terminal keeps printing logs
These are the service logs for the current project. Press Ctrl+C to stop them and unregister the project; the service for other projects is unaffected.
Component market and previews
A component is missing from Recommended / Latest / Popular
The first three lists filter out components with mismatched dependencies. Switch to "All" to confirm it exists, then follow Dependency Matching.
It says a dependency is missing, but it is installed locally
Check in turn: the package name spelling, whether the dependency sits in a subdirectory's node_modules, and whether the page needs a refresh so detection runs again.
The preview works but the downloaded copy does not
The preview uses the dependency versions matched by the platform; the downloaded copy uses your project's versions. Compare against the requirements in the README and upgrade the local package if needed.
Upload and publish
Why is my component not in the public lists
It may have been judged a duplicate, or its dependency status does not meet the recommendation requirements. Duplicate components are only visible in "My Components".
Can I hand-write comp.json
Not recommended. It is generated by the platform and __id__ identifies the component. Breaking it by hand means the component cannot be found on update.
Uploading reports a file limit
Single file ≤ 3 MB, total size ≤ 10 MB, file count ≤ 30. Compress static assets or split the component.
A React component reports no default export
The entry must export default. With named exports only there is no component to render.
Versions and updates
The CLI upload is rejected
The local version is not greater than the online one. Raise version in comp.json; use the update page if you only touched the description or preview configuration.
Can people keep using the old version after an update
Yes. The platform keeps historical versions, so consumers can keep downloading the old one.
Should I retry after a submit times out
Check the latest version on the platform first. If it is already updated, do not retry, to avoid duplicate versions.
Studio
The preview is blank
Wait until dependencies finish installing, then confirm the entry file and its default export. For Web Components, check whether the <script type="module"> in the HTML is inside <body>.
AI does not respond
The platform built-in model requires a login; a custom key must be valid, with the model available.
The workspace is empty after a refresh
Confirm you did not delete the workspace. Studio stores data per workspace in this browser's IndexedDB and does not sync across devices.
A terminal command is blocked
The terminal only allows npm install / npm i / npm add; other commands are not executed.
Error message quick reference
| Prompt | Meaning | Fix |
|---|---|---|
comp-hub must be upgraded before it can start | The current CLI version must be upgraded | Reinstall the latest version |
Local version ... is the published version | The CLI upload did not bump the version | Change the version number |
Component has no default export | The React entry lacks a default export | Change it to export default |
Proxy not found | The request matched no proxy rule | Check the proxy configuration and the /__proxy__ path |
预览文件里没有找到 <script type="module"> | The Web Component preview HTML lacks a module script | Add it inside <body> |
| Missing dependency / dependency missing | The component's dependencies are not installed locally | Install them in the project root |
Glossary
| Term | Meaning |
|---|---|
| Component | A folder containing an entry file and assets; the folder name is the component name |
| Workspace | An independent snapshot of files and conversations inside Studio |
| Dependency matching | The rules deciding whether local dependency versions satisfy a component's requirements |
| Pre-compilation | The platform bundling dependencies ahead of time so previews can load them directly |
| mini / full | The small preview on list cards / the full-screen preview on the detail page |
comp.json | Component metadata: __id__, name, version |
| Component ID | The value of __id__, used to recognise the same component when updating or importing |
| Semantic versioning | major.minor.patch, standing for breaking changes, new features and fixes respectively |
Environment and limits
| Item | Limit |
|---|---|
| Node.js | 16.0.0 or later |
| npm | 8.0.0 or later |
| Single file size | 3 MB |
| Total component size | 10 MB |
| File count | 30 |
| Component name | PascalCase or kebab-case, unique within the same space |
| Tag count | Up to 5 |
Still stuck
Collect information in this order to locate the problem quickly:
- The complete terminal error, not just a summary of the last line.
- The first error in the browser console.
- The component's framework and entry file name.
- Whether the local dependency versions match what the README requires.