Registry

Publish your own registry and get it approved.

Watermelon can consume third-party registries as long as they follow the expected directory entry and component manifest format. Once your registry is live, open a PR to add it to our approved directory.

Overview

The CLI failed earlier because the default registry URL was pointing to a domain that did not exist yet. The fix is not just “host some JSON somewhere”. A registry needs a stable manifest URL pattern, file hosting that matches the manifest, and a scope entry we can review and approve.

If you want your website to work with Watermelon, publish a registry on your own domain, make sure the component manifests resolve correctly, and then submit a PR that adds your directory entry to our approved registry list.

Directory entry

Directory Entry

{
"name": "@your-scope",
"homepage": "https://your-site.com",
"url": "https://your-site.com/r/{name}.json",
"description": "Short summary of your component registry."
}

The name is the namespace users type in the CLI, for example watermelon add @your-scope/card. The url field is a template. Watermelon replaces {name} with the requested component name.

If your registry does not use a template and instead exposes a flat base URL, you can still host manifests at /button.json, /card.json, and so on. The shadcn-style template above is the preferred format because it is more explicit and easier to review.

Component manifest

Component Manifest

{
"name": "button",
"dependencies": ["clsx", "tailwind-merge"],
"registryDependencies": ["text"],
"files": [
  {
    "path": "components/ui/button.tsx",
    "url": "https://your-site.com/files/components/ui/button.tsx"
  }
]
}

Each manifest must include a valid name and at least one files entry. dependencies are npm packages the CLI installs automatically. registryDependencies are other registry components that should be installed first.

Each file needs a target path. You can also provide an explicit url. If you omit the file URL, Watermelon falls back to the conventional /files/<path> pattern.

Hosting behavior

Required Hosting Behavior

GET https://your-site.com/r/button.json
GET https://your-site.com/r/card.json
GET https://your-site.com/files/components/ui/button.tsx
GET https://your-site.com/files/components/ui/card.tsx

Your hosted responses should be public, stable, and return valid JSON or file contents without requiring a browser session. Avoid URLs that depend on temporary tokens, client-side rendering, or HTML wrappers.

Install from registry

How Users Install From Your Registry

watermelon add @your-scope/button
watermelon add @your-scope/card --dry-run
watermelon add @your-scope/button @your-scope/text

PR checklist

PR Checklist

- Host your manifests on a public domain you control.
- Serve a directory entry with a stable `url` template.
- Make every component manifest return valid JSON.
- Make every file URL downloadable directly.
- Include clear descriptions and ownership details.
- Open a PR adding your registry entry to the approved directory.
- We test the URLs, review the output, and approve if everything resolves correctly.