Outshift Logo

Custom Repositories

Extend HAX with custom component repositories to share artifacts, composers, and UI components across teams and organizations.

Overview

Installation

HAX supports multiple component repositories, allowing you to: Share components internally across teams and projects Create private component libraries for your organization Fork and customize existing HAX components Distribute specialized components for specific domains Maintain version control over component updates Custom repositories work alongside the official HAX registry, providing a flexible system for component distribution and management.

A HAX repository follows a standardized structure:

Installation

your-hax-repo/
├── cli/src/registry/github-registry/
│   ├── artifacts.json      # Artifact component metadata
│   ├── ui.json              # UI component metadata
│   └── composers.json       # Composer component metadata
├── hax/
│   ├── artifacts/           # Artifact components
│   ├── components/ui/       # UI components
│   └── composers/           # Composer components
├── templates/               # Component templates
└── docs/                    # Documentation

Setting Up a Custom Repository

Create a new repository structure:

Installation

# Initialize a new HAX registry repository
hax admin init-registry --github=your-org/your-hax-components

# Or initialize locally and push manually
mkdir my-hax-components
cd my-hax-components
hax admin init-registry --local

This creates the required directory structure and metadata files.

Add Components

Add your custom components to the appropriate directories:

Installation

# Add an artifact component
cp -r my-custom-timeline hax/artifacts/
# Update artifacts.json with component metadata

# Add a UI component
cp my-button.tsx hax/components/ui/
# Update ui.json with component metadata

# Add a composer
cp -r my-chat-feature hax/composers/
# Update composers.json with component metadata

Update Registry Metadata

Edit the JSON files to register your components:

Installation

// cli/src/registry/github-registry/artifacts.json
{
  "my-timeline": {
    "type": "registry:artifacts",
    "dependencies": ["react", "date-fns"],
    "registryDependencies": ["button"],
    "files": [
      {
        "name": "timeline.tsx",
        "type": "registry:component"
      },
      {
        "name": "action.ts",
        "type": "registry:hook"
      },
      {
        "name": "types.ts",
        "type": "registry:types"
      },
      {
        "name": "index.ts",
        "type": "registry:index"
      }
    ]
  }
}

Validate Registry

Ensure your repository structure is correct:

Installation

hax admin validate-registry --path=./

Using Custom Repositories

Add a custom repository to your HAX project:

Installation

# Add a GitHub repository
hax repo add internal --github=your-org/internal-components --branch=main

# Add with authentication for private repos
GITHUB_TOKEN=your_token hax repo add internal --github=your-org/private-components

# Add GitHub Enterprise repository
hax repo add enterprise --github=your-org/components --github-url=https://github.yourcompany.com

List Repositories

View configured repositories:

Installation

hax repo list

📦 Configured Repositories:
[default] main: outshift-open/hax (main) (main)
          internal: your-org/internal-components (main)
          enterprise: your-org/components (main)

Install Components

Install components from specific repositories:

Installation

# Install from default repository
hax add artifact my-timeline

# Install from specific repository
hax add artifact my-timeline --repo=your-org/internal-components

# Install with authentication
GITHUB_TOKEN=your_token hax add artifact my-timeline --repo=your-org/private-components

Configuration File

Repositories are stored in your hax.json configuration:

Installation

{
  "registries": {
    "default": "main",
    "fallback": ["main", "internal", "enterprise"],
    "sources": {
      "main": {
        "type": "github",
        "repo": "outshift-open/hax",
        "branch": "main"
      },
      "internal": {
        "type": "github",
        "repo": "your-org/internal-components",
        "branch": "main"
      },
      "enterprise": {
        "type": "github",
        "repo": "your-org/components",
        "branch": "main",
        "githubUrl": "https://github.yourcompany.com"
      }
    }
  }
}

Component Resolution Order

HAX resolves components using this priority order: Environment variable (`HAX_REGISTRY_SOURCE`) if set Local registry (if env is "local" or unset) Default repository from `hax.json` Fallback repositories in order This allows for flexible component sourcing with clear precedence rules.

Authentication

For private repositories, provide authentication:

Installation

# Set GitHub token
export GITHUB_TOKEN="ghp_your_personal_access_token"

# Or pass token via CLI (not recommended for production)
hax add artifact my-component --repo=org/private-repo --token=your_token

© 2025 Outshift. All Rights Reserved.