How It Works

This article is generated by CC powered by GLM-5-turbo based on the project source code.

TL;DR

hpsetup downloads HeroUI Pro's closed-source component tarballs from a CDN using API Key authentication, extracts them into the existing stub packages in the local node_modules, and then automatically fills in peer dependencies and package manager trust configurations.

Full Installation Flow

npx -y hpsetup@latest hp_xxxx
         │
         ▼
   ┌─────────────┐
   │ 1. Env Check │  Package manager · monorepo · platform type
   └──────┬──────┘
          ▼
   ┌─────────────┐
   │ 2. Discovery │  Scan node_modules · identify installed versions
   └──────┬──────┘
          ▼
   ┌─────────────┐
   │ 3. Version   │  Check latest on npm registry · upgrade if outdated
   │    Check     │
   └──────┬──────┘
          ▼
   ┌─────────────┐
   │ 4. Download  │  CDN → local cache fallback
   └──────┬──────┘
          ▼
   ┌─────────────┐
   │ 5. Trust     │  pnpm allowBuilds · bun trustedDeps
   │    Config    │
   └──────┬──────┘
          ▼
   ┌─────────────┐
   │ 6. Peer Deps │  Scan missing · interactive confirm · install per workspace
   └──────┬──────┘
          ▼
   ┌─────────────┐
   │ 7. Finalize  │  Patch package.json · Vercel config
   └─────────────┘

Module Responsibilities

args.js — Argument Parsing

Parses CLI arguments and environment variables to determine whether to run in interactive or automatic mode.

install.js — Core Orchestration

The single flow control center that chains together all the modules below.

discover.js — Package Discovery

Scans node_modules, identifies workspace structure, and detects platform type (Web / Native).

pm.js — Package Manager Abstraction

Unifies install commands and flag differences across npm / yarn / pnpm / bun.

version.js — Version Management

Queries the latest version on the npm registry with incremental timeout retries (3s → 6s → 10s).

download.js — CDN Download

Fetches tarballs from the CDN and extracts them. Falls back to the local cache on failure.

cache.js — Local Cache

Cache directory ~/.heroui/cache/<product>/<version>/; skips download when the same version is already cached.

peers.js — Peer Dependencies

Scans for missing peer dependencies and handles Expo SDK version compatibility mappings.

trust.js — Trust Configuration

pnpm allowBuilds / onlyBuiltDependencies, bun trustedDependencies.

patch.js — Package Patching

Modifies the package.json export paths of Pro packages in node_modules.

vercel.js — Vercel Adaptation

Automatically writes the installCommand into vercel.json.

constants.js — Centralized Configuration

Product definitions, peer dependency lists, Expo SDK compatibility table, and CDN addresses.

Key Mechanisms Explained

Stub Packages and Real Artifacts

HeroUI Pro packages on npm are stub packages — they only contain a postinstall script and no real component code. hpsetup works as follows:

Installs the stub package with --ignore-scripts (so the node_modules/@heroui-pro/react directory exists)

Downloads the tarball containing the real component code from the CDN

Extracts it into the stub package directory, overwriting the empty shell

hpsetup determines whether "real code is installed" by checking for the existence of index.js or index.mjs in the artifact directory, rather than merely checking if the package exists.

Monorepo Support

hpsetup automatically detects workspace structure (the workspaces field in package.json, pnpm-workspace.yaml) and intelligently locates installation targets:

Automatic platform detection: Determines whether each workspace is a Web or Native project based on dependencies and configuration files

Precise installation: React Pro is only installed into Web workspaces; Native Pro is only installed into Native workspaces

Skips shared libraries: Pure library packages under packages/* are not treated as installation targets

Per-workspace peer dependency installation: Each workspace is scanned and installed independently

Download Fault Tolerance

CDN download → current version cache → previous version cache → exit with error

The three-tier fallback ensures installation can still complete during network instability or CDN unavailability.

Package Manager Trust

HeroUI Pro includes a postinstall script that requires package manager trust to execute. hpsetup handles this automatically:

Package Manager	Trust Method
pnpm (with workspace)	`allowBuilds` field in `pnpm-workspace.yaml`
pnpm (without workspace)	`pnpm.onlyBuiltDependencies` field in `package.json`
bun	`trustedDependencies` field in `package.json`
npm / yarn	No additional configuration needed

Vercel Integration

When a Next.js project is detected (presence of next.config.* or vercel.json), hpsetup prompts to write an installCommand into vercel.json so that hpsetup runs automatically during Vercel builds. It also adds vercel.json to .gitignore to prevent API Key leakage.

Expo SDK Compatibility

When installing Native Pro, hpsetup reads the Expo SDK major version from the project and automatically maps peer dependency versions to Expo-compatible pinned versions:

Expo SDK	`@shopify/react-native-skia`
52	1.5.0
53	2.0.0-next.4
54	2.2.12
55	2.4.18

These versions are verified for compatibility by testing each SDK individually with npx expo install.

Interactive Mode vs Automatic Mode

	Interactive Mode	Automatic Mode (`--auto` or CI)
Trigger Condition	TTY terminal	`CI=true` or `--auto`
Product Selection	Multi-select menu	Auto-inferred from package.json
Workspace Selection	Multi-select menu	All matching workspaces
Peer Dependency Confirmation	Multi-select menu (can uncheck)	Install all, no confirmation
Vercel Configuration	Ask for confirmation	Write directly

Known Limitations

Yarn Berry PnP not supported: Add nodeLinker: node-modules to .yarnrc.yml, or use another package manager

pnpm + Vite: May encounter the does not provide an export named 'jsx' error; add optimizeDeps.include to the vite.config

--no-cache rate limit: Maximum once per day; exceeding the limit returns 429

This article is generated by CC powered by GLM-5-turbo based on the project source code.

TL;DR

Full Installation Flow

npx -y hpsetup@latest hp_xxxx
         │
         ▼
   ┌─────────────┐
   │ 1. Env Check │  Package manager · monorepo · platform type
   └──────┬──────┘
          ▼
   ┌─────────────┐
   │ 2. Discovery │  Scan node_modules · identify installed versions
   └──────┬──────┘
          ▼
   ┌─────────────┐
   │ 3. Version   │  Check latest on npm registry · upgrade if outdated
   │    Check     │
   └──────┬──────┘
          ▼
   ┌─────────────┐
   │ 4. Download  │  CDN → local cache fallback
   └──────┬──────┘
          ▼
   ┌─────────────┐
   │ 5. Trust     │  pnpm allowBuilds · bun trustedDeps
   │    Config    │
   └──────┬──────┘
          ▼
   ┌─────────────┐
   │ 6. Peer Deps │  Scan missing · interactive confirm · install per workspace
   └──────┬──────┘
          ▼
   ┌─────────────┐
   │ 7. Finalize  │  Patch package.json · Vercel config
   └─────────────┘

Module Responsibilities

args.js — Argument Parsing

Parses CLI arguments and environment variables to determine whether to run in interactive or automatic mode.

install.js — Core Orchestration

The single flow control center that chains together all the modules below.

discover.js — Package Discovery

Scans node_modules, identifies workspace structure, and detects platform type (Web / Native).

pm.js — Package Manager Abstraction

Unifies install commands and flag differences across npm / yarn / pnpm / bun.

version.js — Version Management

Queries the latest version on the npm registry with incremental timeout retries (3s → 6s → 10s).

download.js — CDN Download

Fetches tarballs from the CDN and extracts them. Falls back to the local cache on failure.

cache.js — Local Cache

Cache directory ~/.heroui/cache/<product>/<version>/; skips download when the same version is already cached.

peers.js — Peer Dependencies

Scans for missing peer dependencies and handles Expo SDK version compatibility mappings.

trust.js — Trust Configuration

pnpm allowBuilds / onlyBuiltDependencies, bun trustedDependencies.

patch.js — Package Patching

Modifies the package.json export paths of Pro packages in node_modules.

vercel.js — Vercel Adaptation

Automatically writes the installCommand into vercel.json.

constants.js — Centralized Configuration

Product definitions, peer dependency lists, Expo SDK compatibility table, and CDN addresses.

Key Mechanisms Explained

Stub Packages and Real Artifacts

HeroUI Pro packages on npm are stub packages — they only contain a postinstall script and no real component code. hpsetup works as follows:

Installs the stub package with --ignore-scripts (so the node_modules/@heroui-pro/react directory exists)

Downloads the tarball containing the real component code from the CDN

Extracts it into the stub package directory, overwriting the empty shell

hpsetup determines whether "real code is installed" by checking for the existence of index.js or index.mjs in the artifact directory, rather than merely checking if the package exists.

Monorepo Support

hpsetup automatically detects workspace structure (the workspaces field in package.json, pnpm-workspace.yaml) and intelligently locates installation targets:

Automatic platform detection: Determines whether each workspace is a Web or Native project based on dependencies and configuration files

Precise installation: React Pro is only installed into Web workspaces; Native Pro is only installed into Native workspaces

Skips shared libraries: Pure library packages under packages/* are not treated as installation targets

Per-workspace peer dependency installation: Each workspace is scanned and installed independently

Download Fault Tolerance

CDN download → current version cache → previous version cache → exit with error

The three-tier fallback ensures installation can still complete during network instability or CDN unavailability.

Package Manager Trust

HeroUI Pro includes a postinstall script that requires package manager trust to execute. hpsetup handles this automatically:

Package Manager	Trust Method
pnpm (with workspace)	`allowBuilds` field in `pnpm-workspace.yaml`
pnpm (without workspace)	`pnpm.onlyBuiltDependencies` field in `package.json`
bun	`trustedDependencies` field in `package.json`
npm / yarn	No additional configuration needed

Vercel Integration

Expo SDK Compatibility

When installing Native Pro, hpsetup reads the Expo SDK major version from the project and automatically maps peer dependency versions to Expo-compatible pinned versions:

Expo SDK	`@shopify/react-native-skia`
52	1.5.0
53	2.0.0-next.4
54	2.2.12
55	2.4.18

These versions are verified for compatibility by testing each SDK individually with npx expo install.

Interactive Mode vs Automatic Mode

	Interactive Mode	Automatic Mode (`--auto` or CI)
Trigger Condition	TTY terminal	`CI=true` or `--auto`
Product Selection	Multi-select menu	Auto-inferred from package.json
Workspace Selection	Multi-select menu	All matching workspaces
Peer Dependency Confirmation	Multi-select menu (can uncheck)	Install all, no confirmation
Vercel Configuration	Ask for confirmation	Write directly

Known Limitations

Yarn Berry PnP not supported: Add nodeLinker: node-modules to .yarnrc.yml, or use another package manager

pnpm + Vite: May encounter the does not provide an export named 'jsx' error; add optimizeDeps.include to the vite.config

--no-cache rate limit: Maximum once per day; exceeding the limit returns 429

This article is generated by CC powered by GLM-5-turbo based on the project source code.

TL;DR

Full Installation Flow

npx -y hpsetup@latest hp_xxxx
         │
         ▼
   ┌─────────────┐
   │ 1. Env Check │  Package manager · monorepo · platform type
   └──────┬──────┘
          ▼
   ┌─────────────┐
   │ 2. Discovery │  Scan node_modules · identify installed versions
   └──────┬──────┘
          ▼
   ┌─────────────┐
   │ 3. Version   │  Check latest on npm registry · upgrade if outdated
   │    Check     │
   └──────┬──────┘
          ▼
   ┌─────────────┐
   │ 4. Download  │  CDN → local cache fallback
   └──────┬──────┘
          ▼
   ┌─────────────┐
   │ 5. Trust     │  pnpm allowBuilds · bun trustedDeps
   │    Config    │
   └──────┬──────┘
          ▼
   ┌─────────────┐
   │ 6. Peer Deps │  Scan missing · interactive confirm · install per workspace
   └──────┬──────┘
          ▼
   ┌─────────────┐
   │ 7. Finalize  │  Patch package.json · Vercel config
   └─────────────┘

Module Responsibilities

args.js — Argument Parsing

Parses CLI arguments and environment variables to determine whether to run in interactive or automatic mode.

install.js — Core Orchestration

The single flow control center that chains together all the modules below.

discover.js — Package Discovery

Scans node_modules, identifies workspace structure, and detects platform type (Web / Native).

pm.js — Package Manager Abstraction

Unifies install commands and flag differences across npm / yarn / pnpm / bun.

version.js — Version Management

Queries the latest version on the npm registry with incremental timeout retries (3s → 6s → 10s).

download.js — CDN Download

Fetches tarballs from the CDN and extracts them. Falls back to the local cache on failure.

cache.js — Local Cache

Cache directory ~/.heroui/cache/<product>/<version>/; skips download when the same version is already cached.

peers.js — Peer Dependencies

Scans for missing peer dependencies and handles Expo SDK version compatibility mappings.

trust.js — Trust Configuration

pnpm allowBuilds / onlyBuiltDependencies, bun trustedDependencies.

patch.js — Package Patching

Modifies the package.json export paths of Pro packages in node_modules.

vercel.js — Vercel Adaptation

Automatically writes the installCommand into vercel.json.

constants.js — Centralized Configuration

Product definitions, peer dependency lists, Expo SDK compatibility table, and CDN addresses.

Key Mechanisms Explained

Stub Packages and Real Artifacts

HeroUI Pro packages on npm are stub packages — they only contain a postinstall script and no real component code. hpsetup works as follows:

Installs the stub package with --ignore-scripts (so the node_modules/@heroui-pro/react directory exists)

Downloads the tarball containing the real component code from the CDN

Extracts it into the stub package directory, overwriting the empty shell

hpsetup determines whether "real code is installed" by checking for the existence of index.js or index.mjs in the artifact directory, rather than merely checking if the package exists.

Monorepo Support

hpsetup automatically detects workspace structure (the workspaces field in package.json, pnpm-workspace.yaml) and intelligently locates installation targets:

Automatic platform detection: Determines whether each workspace is a Web or Native project based on dependencies and configuration files

Precise installation: React Pro is only installed into Web workspaces; Native Pro is only installed into Native workspaces

Skips shared libraries: Pure library packages under packages/* are not treated as installation targets

Per-workspace peer dependency installation: Each workspace is scanned and installed independently

Download Fault Tolerance

CDN download → current version cache → previous version cache → exit with error

The three-tier fallback ensures installation can still complete during network instability or CDN unavailability.

Package Manager Trust

HeroUI Pro includes a postinstall script that requires package manager trust to execute. hpsetup handles this automatically:

Package Manager	Trust Method
pnpm (with workspace)	`allowBuilds` field in `pnpm-workspace.yaml`
pnpm (without workspace)	`pnpm.onlyBuiltDependencies` field in `package.json`
bun	`trustedDependencies` field in `package.json`
npm / yarn	No additional configuration needed

Vercel Integration

Expo SDK Compatibility

When installing Native Pro, hpsetup reads the Expo SDK major version from the project and automatically maps peer dependency versions to Expo-compatible pinned versions:

Expo SDK	`@shopify/react-native-skia`
52	1.5.0
53	2.0.0-next.4
54	2.2.12
55	2.4.18

These versions are verified for compatibility by testing each SDK individually with npx expo install.

Interactive Mode vs Automatic Mode

	Interactive Mode	Automatic Mode (`--auto` or CI)
Trigger Condition	TTY terminal	`CI=true` or `--auto`
Product Selection	Multi-select menu	Auto-inferred from package.json
Workspace Selection	Multi-select menu	All matching workspaces
Peer Dependency Confirmation	Multi-select menu (can uncheck)	Install all, no confirmation
Vercel Configuration	Ask for confirmation	Write directly

Known Limitations

Yarn Berry PnP not supported: Add nodeLinker: node-modules to .yarnrc.yml, or use another package manager

pnpm + Vite: May encounter the does not provide an export named 'jsx' error; add optimizeDeps.include to the vite.config

--no-cache rate limit: Maximum once per day; exceeding the limit returns 429

How It Works

args.js — Argument Parsing

install.js — Core Orchestration

discover.js — Package Discovery

pm.js — Package Manager Abstraction

version.js — Version Management

download.js — CDN Download

cache.js — Local Cache

peers.js — Peer Dependencies

trust.js — Trust Configuration

patch.js — Package Patching

vercel.js — Vercel Adaptation

constants.js — Centralized Configuration

On this page

How It Works

args.js — Argument Parsing

install.js — Core Orchestration

discover.js — Package Discovery

pm.js — Package Manager Abstraction

version.js — Version Management

download.js — CDN Download

cache.js — Local Cache

peers.js — Peer Dependencies

trust.js — Trust Configuration

patch.js — Package Patching

vercel.js — Vercel Adaptation

constants.js — Centralized Configuration

On this page

How It Works

args.js — Argument Parsing

install.js — Core Orchestration

discover.js — Package Discovery

pm.js — Package Manager Abstraction

version.js — Version Management

download.js — CDN Download

cache.js — Local Cache

peers.js — Peer Dependencies

trust.js — Trust Configuration

patch.js — Package Patching

vercel.js — Vercel Adaptation

constants.js — Centralized Configuration

On this page