How to Publish a UI Package
How to Publish a UI Package
Section titled “How to Publish a UI Package”In XSite, each UI component is treated as an independent package.
For example:
@xsite/ui-cta1@xsite/ui-hero2@xsite/ui-about1
This guide explains the standard workflow for building, versioning, and publishing a single UI component package to the package registry.
Prerequisites
Section titled “Prerequisites”Before publishing, ensure:
- You have created or modified a UI component inside
packages/ui - Your local environment is set up with
pnpm - You are authenticated with the package registry (Verdaccio)
- The component builds successfully
Step 1: Create a Changeset (Required First)
Section titled “Step 1: Create a Changeset (Required First)”Before building or publishing a component, you must record what changed using Changesets. This ensures proper versioning and release tracking.
Command
Section titled “Command”npx changesetWhat Happens
Section titled “What Happens”- You will be prompted to select unreleased / changed packages
- Choose the UI package you modified (e.g.,
@xsite/ui-cta1) - Select the version bump type:
- major – breaking changes
- minor – new features
- patch – fixes or small updates
- Add a short description of what changed
- A changeset file will be generated inside .changeset/
Step 2: Apply Version Updates
Section titled “Step 2: Apply Version Updates”After creating the changeset, apply the version bump.
Command
Section titled “Command”npx changeset versionWhat This Command Does
Section titled “What This Command Does”- Updates the package version in
package.json - Updates any dependent packages if required
- Prepares the repository for publishing
At this point, the package is versioned and ready to publish.
Step 3: Build the Component Package
Section titled “Step 3: Build the Component Package”After the changeset is created, build only the modified component package.
Command
Section titled “Command”pnpm build:component @xsite/ui-[your_component_name]Example:
pnpm build:component @xsite/ui-cta1What This Command Does
Section titled “What This Command Does”- Builds the selected UI package (
@xsite/ui-cta1) - Ensures all internal and external dependencies are properly resolved
- Produces the distributable output (compiled files ready for publishing)
⚠️ Important: If the build fails, do not proceed to the next steps. Fix all build errors first.
Step 4: Publish the Package
Section titled “Step 4: Publish the Package”Finally, publish the updated package to the appropriate package registry. Packages can be published to staging (development) or production, depending on the release target.
Commands
Section titled “Commands”Publish to Staging (Development)
Section titled “Publish to Staging (Development)”pnpm publish:pkg:staging @xsite/ui-[your_component_name]Example:
pnpm publish:pkg:staging @xsite/ui-cta1Publish to Production
Section titled “Publish to Production”pnpm publish:pkg:production @xsite/ui-[your_component_name]Example:
pnpm publish:pkg:production @xsite/ui-cta1What This Command Does
Section titled “What This Command Does”- Publish only the specified UI package
- Do not affect other UI components
- Use the updated version generated in the previous steps
- Target the correct registry based on the command:
- Staging → development/testing environment
- Production → live environment
Final Result
Section titled “Final Result”If all steps complete successfully:
- The package is published to Verdaccio
- The new version becomes available for consumption
- XSite can now use the updated component at runtime
⚠️ Common Mistakes to Avoid:
Section titled “⚠️ Common Mistakes to Avoid:”- Skipping the build step
- Publishing without creating a changeset
- Selecting the wrong version bump type
- Forgetting to authenticate with Verdaccio