How the Astryx Swizzle CLI Command Ejects Components for Deep Customization

The astryx swizzle CLI command acts as a thin wrapper around the internal swizzle API, copying component source files from their owner package to your local directory while automatically rewriting imports and warning about StyleX dependencies.

The astryx swizzle CLI command enables developers to extract component source code from the Astryx design system for deep customization without breaking functionality. When you run this command, it delegates all heavy-lifting to the internal swizzle API located at packages/cli/api/swizzle/swizzle.mjs, ensuring you receive a fully functional local copy with properly rewritten import paths and necessary dependency warnings.

How the Swizzle CLI Command Works

The command itself performs minimal logic. According to the facebook/astryx source code, the CLI wrapper in packages/cli/clients/cli/commands/swizzle.mjs only parses CLI flags, formats output messages, and invokes the core swizzle API. The actual ejection logic resides entirely in packages/cli/api/swizzle/swizzle.mjs, which executes a five-step process to safely extract components.

Component Resolution and Source Copying

The API first discovers the component’s owning package (for example, @astryxdesign/buttons). It then locates all source files implementing that component and copies them to your specified directory, defaulting to src/components/<Component>. This ensures you receive the complete implementation, including utilities and sub-components required for the component to function.

Import Rewriting Logic

Inside the copied files, the API scans for relative imports that originally pointed to the owner package. It rewrites these paths to reference the new local location, while leaving external package imports untouched. This guarantees the component works unchanged immediately after copying, without requiring manual path updates or broken references.

StyleX Detection and Warnings

The API scans the copied component for StyleX usage. If it detects StyleX code, it prints a warning that a StyleX compiler must be present in your consumer project. Without this compiler, the swizzled component renders unstyled. This prevents silent failures when developers eject styled components without the proper build pipeline.

Maintainer Feedback Integration

If the original component maintainer supplied a feedback URL or pre-filled GitHub issue command in the package metadata, the CLI prints this link after successful ejection. This allows you to notify the design-system team why you needed to swizzle, providing valuable telemetry for component improvements.

Practical Usage Examples

The astryx swizzle command supports several flags for different workflows:

# List all swizzle-able components without copying

astryx swizzle --list

# Output: Button, Card, Modal …

# Swizzle a component to the default location

astryx swizzle Button

# Copies to ./src/components/Button, rewrites imports,

# and prints StyleX warnings if detected

# Specify a custom output directory

astryx swizzle Modal --output src/custom/Modal

# Force overwrite an existing copy

astryx swizzle Card --overwrite

# Target a component from a different package

astryx swizzle XDSButton --package @astryxdesign/xds

# Get JSON output for programmatic consumption

astryx swizzle Button --json

Key Implementation Files

The swizzle functionality spans several files within the facebook/astryx repository:

• packages/cli/clients/cli/commands/swizzle.mjs – The CLI wrapper that parses flags, handles user output formatting, and delegates to the API.
• packages/cli/api/swizzle/swizzle.mjs – The core implementation containing owner resolution, file copying, import rewriting, StyleX detection, and feedback emission logic.
• packages/cli/api/swizzle/swizzle.type.mjs – Type definitions for swizzle responses, distinguishing between list operations and copy operations.
• packages/cli/clients/cli/commands/swizzle.doc.mjs – Documentation displayed by astryx docs swizzle and the --help output.
• packages/cli/api/swizzle/swizzle.doc.mjs – API-level documentation imported by the CLI wrapper for its function field descriptions.

Summary

• The swizzle CLI command is a thin wrapper that delegates to packages/cli/api/swizzle/swizzle.mjs.
• It copies component source files to src/components/<Component> by default, with customizable output paths via --output.
• Import rewriting automatically adjusts relative paths to point to the new local location while preserving external dependencies.
• StyleX detection warns when the consumer project lacks the necessary compiler to process extracted styles.
• Maintainer feedback hooks allow communication with design system teams when components require ejection.

Frequently Asked Questions

What is the difference between the swizzle CLI command and the swizzle API?

The swizzle CLI command (packages/cli/clients/cli/commands/swizzle.mjs) handles argument parsing, user-facing output formatting, and help documentation. The swizzle API (packages/cli/api/swizzle/swizzle.mjs) contains the core logic for component resolution, file copying, import rewriting, and StyleX detection. The CLI simply invokes the API and presents the results.

Does swizzling a component remove the dependency on the original package?

Swizzling copies the source files to your local directory and rewrites internal imports, but it does not automatically remove the original package from your dependencies. You must manually uninstall the package if you no longer need the non-swizzled version, ensuring you do not import both the original and the local copy simultaneously.

How does the swizzle command handle StyleX styles when ejecting components?

When the swizzle API detects StyleX usage in the component source, it prints a warning to the console stating that a StyleX compiler must be present in your consumer project. The component will render unstyled if your build pipeline lacks StyleX support, as the copied files retain their original style definitions.

Can I swizzle components from custom packages outside the core Astryx design system?

Yes. Use the --package flag to target components from any compatible package. For example, astryx swizzle XDSButton --package @astryxdesign/xds tells the resolver to look for the XDSButton component within the specified package rather than the default @astryxdesign scope.

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