Skip to content
WebJs
Menu

GitHub Registries

Use a GitHub repository as a registry.

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.

pnpm dlx @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.

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 and 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:

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.

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.

pnpm dlx @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.

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.

pnpm dlx @webjsdev/ui list --registry https://raw.githubusercontent.com/acme/toolkit/main/r
pnpm dlx @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.

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.

pnpm dlx @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.

pnpm dlx @webjsdev/ui add project-conventions --registry https://raw.githubusercontent.com/acme/toolkit/main/r

Compare installed files against the registry.

pnpm dlx @webjsdev/ui diff --registry https://raw.githubusercontent.com/acme/toolkit/main/r

Set the base URL once for a session.

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.

pnpm dlx @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 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.