HAX

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

Website Terms of Use Privacy PolicyTrademarks

Overview

Installation

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

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

Website Terms of Use Privacy PolicyTrademarks

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

# 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

# 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

// 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"

}

]

}

# 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

# 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

{

"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"

}

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

# 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

# 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

// 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"

}

]

}

# 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

# 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

{

"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"

}