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

> Automatically discover Astryx compatible external packages for your project. Run xds discover to list packages, versions, and metadata for seamless integration.

- Repository: [Meta/astryx](https://github.com/facebook/astryx)
- Tags: how-to-guide
- Published: 2026-07-02

---

**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:

```bash
xds --json discover

```

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

```json
{
  "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:

```bash
xds --json discover @myorg/ui-kit

```

Returns:

```json
{
  "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:

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

```

Returns:

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

```

For free-text search across all compatible packages:

```bash
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.