How to Add SXOUI Components Using the sxo add Command

The sxo add command pulls SXOUI components from the basecoat library into your local src/components directory by resolving CLI flags, fetching files from GitHub or a local fallback, and writing them to the configured destination.

The sxo CLI provides a streamlined workflow for integrating pre-built UI components into your projects. According to the gc-victor/sxo source code, the sxo add command automates downloading and installing SXOUI components from the basecoat library. This guide explains the internal mechanics of flag resolution, configuration merging, and component installation based on the actual implementation in src/js/cli/commands/add.js.

Understanding the sxo add Command Workflow

The sxo add command processes component requests through three distinct stages defined in src/js/cli/commands/add.js. The entry point handleAddCommand (lines 84-103) orchestrates the workflow: resolving the project root, ensuring the destination directory exists, invoking addComponent, and setting the appropriate exit code based on success or failure.

Stage 1: Flag Handling and Configuration Setup

First, the command invokes prepareFlags from src/js/cli/cli-helpers.js (lines 55-66). This utility extracts only the flags relevant to the add sub-command, including --verbose, --color, and --components-dir. It returns a clean flagsForConfig object alongside a map indicating which flags were explicitly passed by the user.

Stage 2: Configuration Resolution

Next, resolveConfig in src/js/config.js (lines 30-39) merges multiple configuration sources to determine the final environment. It combines default values, environment variables, settings from an optional sxo.config.* file, and the explicit CLI flags processed earlier. This resolution yields the definitive componentsDir path, defaulting to src/components if no override is specified.

Stage 3: Component Download and Installation

Finally, the addComponent function (lines 18-33) handles the actual file operations. For each requested component, it attempts to fetch three file types—.jsx, .client.js, and .css—from a remote GitHub raw URL. If the network request fails, it falls back to the local copy stored in the repository's components/src/components directory. Successfully retrieved files are written to the resolved componentsDir, with progress logged via log.info (lines 64-68). If none of the requested files are found, the command exits with a non-zero status and prints an error via log.error (lines 97-100).

Running the sxo add Command

You can invoke the command directly from your terminal or integrate it programmatically into build pipelines.

Basic Component Installation

To add a single component to your project, specify the component name after the add keyword:

sxo add button

This creates src/components/button.jsx, src/components/button.client.js, and src/components/button.css assuming the default configuration.

Advanced CLI Options

Override default behavior using explicit flags. The --components-dir flag changes the destination folder, while --verbose and --no-color control output formatting:

sxo add modal --components-dir custom/ui --no-color --verbose

Programmatic Integration

For custom build scripts or automated workflows, import handleAddCommand directly from the source:

import { handleAddCommand } from "./src/js/cli/commands/add.js";

await handleAddCommand("card", { verbose: true });

Summary

• The sxo add command installs SXOUI components by processing CLI flags through prepareFlags in src/js/cli/cli-helpers.js, resolving configuration via src/js/config.js, and downloading files via addComponent in src/js/cli/commands/add.js.
• Components are fetched from remote GitHub URLs first, with a local fallback to components/src/components in the repository if network requests fail.
• The default installation directory is src/components, configurable via the --components-dir flag or sxo.config.* files.
• The command exits with a non-zero status code if it cannot locate any of the requested component files.

Frequently Asked Questions

What flags does the sxo add command support?

The command recognizes --verbose for detailed logging, --color / --no-color to toggle ANSI color output, and --components-dir to specify a custom destination path. These flags are processed by prepareFlags in src/js/cli/cli-helpers.js (lines 55-66) before configuration resolution begins.

Where does sxo add download components from?

By default, addComponent attempts to fetch files from a remote GitHub raw URL corresponding to the basecoat library. If the network request fails, it automatically falls back to the local copy stored in the repository's components/src/components directory, as implemented in src/js/cli/commands/add.js (lines 18-33).

Can I use sxo add programmatically in my own scripts?

Yes. Import handleAddCommand from src/js/cli/commands/add.js and await its execution with the component name and an options object. This allows integration into custom build pipelines or automated setup scripts without invoking the CLI directly.

What happens if a component download fails?

If addComponent cannot retrieve any of the required files (.jsx, .client.js, or .css) from either the remote source or local fallback, it logs an error via log.error and sets process.exitCode to a non-zero value, causing the command to fail visibly (lines 97-100).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}