# GitHub Registries

Use a GitHub repository as a registry.

Source: https://webjs.dev/ui/docs/registry/github

You can turn **a public GitHub repository into a registry.**

Add a `registry.json` file to the repository, build it, commit the output, and users can install from the repository's raw file URL with the WebJs UI CLI.

```bash
npx @webjsdev/ui add <item> --registry https://raw.githubusercontent.com/acme/toolkit/main/r
```

**Note:** The CLI fetches built item files from a base URL, so the repository has to contain the `build` output, and the address is the URL of the folder that holds it.

## Distribute Anything

Registry items are **not limited to components.** They can include any text file from your repository: source files, configuration, docs, templates, agent rules or project conventions. Each file names where it lands in the user's project with a `target`.

```json title="registry.json"
{
  "name": "acme",
  "homepage": "https://github.com/acme/toolkit",
  "items": [
    {
      "name": "project-conventions",
      "type": "registry:item",
      "title": "Project Conventions",
      "description": "Agent rules and editor settings for Acme apps.",
      "files": [
        {
          "path": "rules/conventions.md",
          "type": "registry:file",
          "target": ".agents/rules/conventions.md"
        },
        {
          "path": "config/settings.json",
          "type": "registry:file",
          "target": ".vscode/settings.json"
        }
      ]
    }
  ]
}
```

## When to use GitHub

Use a GitHub repository as a registry when:

- You already have reusable code in a public GitHub repository.
- You want to distribute components, helpers, config files, rules, docs or templates from the same repository.
- You do not want to run a registry server.

## Requirements

A GitHub registry must:

- Be a public repository, since the CLI sends no credentials.
- Have a `registry.json` that conforms to the [registry.json](https://webjs.dev/ui/docs/registry/registry-json) and [registry-item.json](https://webjs.dev/ui/docs/registry/registry-item-json) schemas.
- Commit the files `webjsui build` writes, one `<name>.json` per item plus `index.json`.

## Step 1: Add registry.json

Given an existing repository:

```txt
acme/toolkit
├── components
│   └── brand-button.ts
├── lib
│   └── utils.ts
└── rules
    └── conventions.md
```

Add a `registry.json` at the root that lists the items to share. Paths are relative to `registry.json`.

```json title="registry.json"
{
  "name": "acme",
  "homepage": "https://github.com/acme/toolkit",
  "items": [
    {
      "name": "brand-button",
      "type": "registry:ui",
      "description": "A button in the Acme brand colors.",
      "files": [
        { "path": "components/brand-button.ts", "type": "registry:ui" }
      ]
    },
    {
      "name": "project-conventions",
      "type": "registry:item",
      "description": "Agent rules for Acme apps.",
      "files": [
        {
          "path": "rules/conventions.md",
          "type": "registry:file",
          "target": ".agents/rules/conventions.md"
        }
      ]
    }
  ]
}
```

## Step 2: Build and commit

Run `build` from the repository root. It inlines each file's content into `r/<name>.json` and writes `r/index.json`.

```bash
npx @webjsdev/ui build
```

Commit the `r` folder. Rebuild and commit again whenever a source file changes, since users install the built JSON, not the source files.

```txt
acme/toolkit
├── r
│   ├── brand-button.json
│   ├── project-conventions.json
│   ├── index.json
│   └── registry.json
└── registry.json
```

## Step 3: Validate the registry

`build` validates as it writes: it parses `registry.json` against the registry schema and every item against the item schema, and stops with the error on the first one that does not conform. A file listed under `path` that does not exist fails the build too.

## Step 4: List and search items

The base URL is the raw URL of the committed `r` folder: `https://raw.githubusercontent.com/<owner>/<repo>/<ref>/r`.

```bash
npx @webjsdev/ui list --registry https://raw.githubusercontent.com/acme/toolkit/main/r
```

```bash
npx @webjsdev/ui search button --registry https://raw.githubusercontent.com/acme/toolkit/main/r
```

`list` shows the items typed `registry:ui` and `registry:block`. An item of another type, such as `project-conventions` above, installs with `add` and prints with `view`, but is not listed.

## Organize the repository

Keep one `registry.json` in the repository, and organize the source files in folders as you like, since each item's `path` points at its files wherever they are.

## Registry dependencies

A `registryDependencies` entry is the name of another item, and it is fetched from the same base URL as the item that lists it. So an item in your repository can depend on another item in your repository by name.

```json title="registry.json"
{
  "name": "hello-world",
  "type": "registry:block",
  "registryDependencies": ["brand-button"],
  "files": [
    {
      "path": "blocks/hello-world/page.ts",
      "type": "registry:page",
      "target": "app/hello/page.ts"
    }
  ]
}
```

Every dependency comes from the item's own registry. A name like `button` resolves to `button.json` in your repository, not to the WebJs UI `button`. To build on a kit component, tell users to install it first with `webjs ui add button`, or ship your own copy as an item.

## Useful commands

View an item before installing it. `view` prints what the item is and then the source of every file it would write.

```bash
npx @webjsdev/ui view project-conventions --registry https://raw.githubusercontent.com/acme/toolkit/main/r
```

Install an item into a project that has a `components.json`.

```bash
npx @webjsdev/ui add project-conventions --registry https://raw.githubusercontent.com/acme/toolkit/main/r
```

Compare installed files against the registry.

```bash
npx @webjsdev/ui diff --registry https://raw.githubusercontent.com/acme/toolkit/main/r
```

Set the base URL once for a session.

```bash
export REGISTRY_URL=https://raw.githubusercontent.com/acme/toolkit/main/r
npx @webjsdev/ui add brand-button
```

## Refs

The ref is part of the raw URL. Use a branch to track the latest commit, or a tag or a full commit SHA to pin the files users install.

```bash
npx @webjsdev/ui add brand-button --registry https://raw.githubusercontent.com/acme/toolkit/v1.2.0/r
```

For published install commands, prefer tags or full commit SHAs. A registry dependency is fetched from the same URL, so it is pinned to the same ref.

## Private repositories

To keep a registry private, serve its build output from a host you control: `raw.githubusercontent.com` answers a private file only with a token, and the CLI fetches with a plain request. See [Authentication](https://webjs.dev/ui/docs/registry/authentication) for the patterns, a private network or a secret path segment.

## Review before installing

Registry items install code and project files from another repository. Treat a registry URL like any other third-party code dependency.

Before installing from a source you do not control:

- Review the repository, its `registry.json` and the built item files.
- Review the item definition, especially `files`, `target`, `dependencies`, `devDependencies` and `registryDependencies`.
- Prefer a tag or full commit SHA in the URL. A full 40-character commit SHA is the most reproducible option.
- Run `view` to print the item and every file's source before installing. Pipe its output to your agent or review tool if you want help checking the item.
- `add` asks before replacing an existing file, unless you pass `--yes` or `--overwrite`, and keeps an existing block file unless you pass `--overwrite`. Review with `view` first, and run `diff` afterwards to compare what is installed.
