How to Discover External Packages Compatible with Astryx Using the `discover` Command

Run xds --json discover to automatically scan your project for integrations that expose a components root, returning a JSON payload listing every compatible external package with its exported components, version, and metadata.

The Astryx design system CLI provides a powerful mechanism to enumerate external packages that conform to the XDS component contract. Whether you are working with internal UI kits or third-party libraries, the discover command automates the detection of compatible integrations by scanning for directories containing XDS component documentation. Understanding how to discover external packages compatible with Astryx is essential for efficiently managing component libraries within the facebook/astryx ecosystem.

How the Discover Command Works

When you execute xds --json discover, Astryx initiates a four-step discovery process defined in packages/cli/src/api/discover.mjs:

1. Project Configuration Loading: The command first invokes Project.load() (implemented in packages/cli/src/lib/project.mjs) to load the project's configuration and resolve all loaded integrations.
2. Integration Filtering: It filters for integrations that declare a components field, which indicates the presence of a components root directory containing XDS documentation.
3. Package Generation: Each valid integration is transformed into a "scannable package" object containing name, version, category, and docsDir properties.
4. Directory Scanning: These packages are passed to the package scanner (in packages/cli/src/lib/package-scanner.mjs), which walks the docsDir hierarchy to build a complete list of exported components.

If no integrations declare a components root, the command returns an empty list with meta.configured: false.

Running the Discover Command

To list every discovered package in your project, including external integrations, run:

xds --json discover

The command returns a JSON payload with package metadata and component arrays:

{
  "type": "discover.list",
  "data": [
    {
      "name": "@astryxdesign/core",
      "category": "@astryxdesign/core",
      "components": ["Button", "Card", "..."],
      "version": "1.3.0",
      "description": "Core XDS component library",
      "displayName": "Astryx Core"
    },
    {
      "name": "@myorg/ui-kit",
      "category": "@myorg/ui-kit",
      "components": ["Switch", "Modal"],
      "version": "0.5.2",
      "description": "Internal UI kit",
      "displayName": "MyOrg UI Kit"
    }
  ],
  "meta": { "configured": true }
}

Querying Specific Packages and Components

You can filter the discovery results by passing a package name, component path, or search term as an argument.

To retrieve details for a specific external package:

xds --json discover @myorg/ui-kit

Returns:

{
  "type": "discover.detail",
  "data": {
    "name": "@myorg/ui-kit",
    "category": "@myorg/ui-kit",
    "components": ["Switch", "Modal"],
    "version": "0.5.2",
    "description": "Internal UI kit",
    "displayName": "MyOrg UI Kit"
  }
}

To get documentation for a specific component within an external package:

xds --json discover @myorg/ui-kit/Modal

Returns:

{
  "type": "discover.detail.doc",
  "data": {
    "name": "Modal",
    "usage": { "description": "...", "bestPractices": [...] },
    "props": [...],
    "components": [...]
  }
}

For free-text search across all compatible packages:

xds --json discover modal

When multiple components match, Astryx returns a discover.search payload containing all matches.

Key Source Files and Implementation

The discovery functionality spans several modules in the facebook/astryx repository:

• packages/cli/src/api/discover.mjs: Contains the main discover() function (lines 41-44) and the logic (lines 53-62) that converts integrations with components roots into scannable packages.
• packages/cli/src/lib/project.mjs: Handles project configuration loading and exposes loadedIntegrations used by the discovery process.
• packages/cli/src/lib/package-scanner.mjs: Traverses each integration's components directory and returns normalized package descriptions.
• packages/cli/src/lib/component-loader.mjs: Loads and validates component documentation files (*.doc.mjs) before they are returned by the discover command.

Summary

• Run xds --json discover to enumerate all external packages compatible with Astryx that expose a components root.
• The command scans integrations declared in your project configuration, filtering for those with a components field.
• Output includes package metadata (name, version, category, displayName, description) and an array of exported component names.
• Use query arguments to filter by package name (@scope/package), component path (@scope/package/Component), or free-text search.
• If no integrations are configured with components, the response includes meta.configured: false.

Frequently Asked Questions

What makes a package "compatible" with Astryx discovery?

A package is compatible when it is registered as an integration in your project configuration and declares a components root directory. This directory must contain XDS component documentation that the scanner can traverse. According to the source code in packages/cli/src/api/discover.mjs, only integrations with a defined components field are converted into scannable packages (lines 53-62).

Why does my discover command return an empty list with "configured: false"?

This occurs when no loaded integrations in your project declare a components field. The discovery logic explicitly checks for this property and returns meta.configured: false when no qualifying integrations are found. Ensure your external packages are properly registered in the project configuration with a valid components directory path.

Can I discover individual components without knowing the exact package name?

Yes. You can use free-text search by passing a partial name or component type to the discover command (e.g., xds --json discover modal). Astryx will return a discover.search payload containing all matching components across all compatible external packages. The matching logic is implemented in the discover.mjs API module.

How does Astryx validate component documentation during discovery?

The discovery process uses packages/cli/src/lib/component-loader.mjs to load each component's documentation file (typically *.doc.mjs). This module validates the documentation shape before including it in the discovery output, ensuring that only properly formatted XDS components are exposed through the CLI.

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