Upstream Component Sync
Relevant source files
The following files were used as context for generating this wiki page:
Upstream Component Sync identifies the process and automation used to synchronize source code from the open-vetta project into the HX-UI repository. Since the upstream project does not publish its UI packages to a registry, HX-UI maintains its visual identity by copying source files and refactoring internal package references while preserving original CSS class names.
Sources: scripts/sync-upstream.sh:3-10, README.md:104-106
Synchronization Architecture
The synchronization system uses a Bash script to automate the retrieval, modification, and organization of upstream components. It prioritizes the preservation of the "Open Vetta" design language by ensuring that visual class names remain unchanged during the transition.
Sync Workflow Logic
The sync process follows a strict sequence to prevent the loss of local modifications while updating core primitives and layout components.
The workflow ensures that manual components not present in the upstream are preserved in a temporary location before the source directory is refreshed.
Sources: scripts/sync-upstream.sh:13-56
Component Categorization
The project categorizes synced components into two primary layers: Primitives and Layout. This distinction determines where files are stored and how their import statements are refactored.
| Layer | Source Package | Destination | Description |
|---|---|---|---|
| Primitives | packages/ui | src/primitives/ | Basic UI elements like Button, Input, and Switch built on Radix UI. |
| Layout | packages/theme-ui | src/layout/ | Structural components like AppFrame and SettingChrome. |
Sources: scripts/sync-upstream.sh:32-52, src/index.ts:3-12, README.md:12-16
Import Refactoring Process
The synchronization script performs automated text transformation to ensure that components correctly reference local utilities instead of the upstream @vetta-org/ui package.
Transformation Rules
- Package Re-mapping: Replaces all instances of
from "@vetta-org/ui"with relative paths to./primitives/utilsor../primitives/utils. - Relative Path Correction: Adjusts internal relative imports (e.g.,
./utils) to maintain consistency within the new directory structure. - Depth Detection: Uses a dynamic depth check based on the file's location to determine the correct number of parent directory jumps required for the relative path.
Sources: scripts/sync-upstream.sh:58-70
Integration and Verification
Synchronized components are integrated into the library via a central export file and verified through a build pipeline.
Build and Verification Scripts
The following npm scripts manage the lifecycle of synced code:
npm run sync-upstream: Executes the Bash script to pull fresh code.npm run build: Runs TypeScript type checking and enforces UI design rules.npm run verify: Performs a full build, documentation site build, and browser smoke tests.
Sources: package.json:23-31, README.md:92-97
Metadata Preservation
The system tracks the specific upstream state by writing the current Git HEAD of the source repository into an UPSTREAM_COMMIT file. It also synchronizes legal documentation by copying LICENSE and NOTICE files from the upstream project.
Sources: scripts/sync-upstream.sh:42-45
Conclusion
Upstream Component Sync allows HX-UI to stay updated with the open-vetta design system without relying on non-existent NPM packages. By automating the refactoring of imports and preserving local-only components, the system maintains a consistent visual language while providing a stable, self-contained UI library.