# How to File Gap Reports for Missing Features in Astryx Components

> Easily file gap reports for missing Astryx features using the built-in CLI command. Record issues via interactive prompt or JSON API for seamless development.

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

---

**Astryx provides a built-in `gap-report` CLI command that lets designers and developers record missing functionality through an interactive prompt or automated JSON API, with optional backend integration via `astryx.config.mjs`.**

The Astryx design system from Facebook includes a specialized workflow for capturing "gaps"—missing features, undocumented behavior, or UX inconsistencies encountered while working with components. This article explains how to file gap reports for missing features in Astryx components using the CLI tool, configuration options, and programmatic interfaces defined in the source code.

## Configuring the Gap Report Endpoint

While the `gap-report` command works out of the box, you can optionally route submissions to a custom backend by configuring the `gapReport` section in your project's configuration file.

### Setting up astryx.config.mjs

Add a `gapReport` object to your `astryx.config.mjs` file to specify where reports should be sent:

```javascript
// astryx.config.mjs
export default {
  // …other config…
  gapReport: {
    url: 'https://your-api.com/gaps',
  },
};

```

According to the CLI documentation in [`packages/cli/README.md`](https://github.com/facebook/astryx/blob/main/packages/cli/README.md) (lines 32-40), when this URL is configured, the CLI automatically POSTs JSON payloads to your endpoint. Without this configuration, the command stores reports locally or generates a pre-filled GitHub issue template.

## Running the Interactive Gap Reporter

The primary interface for filing gap reports is the interactive CLI wizard. This workflow guides users through categorization and documentation of the missing feature.

### Listing Available Categories

Before filing a report, you can view all supported categories to ensure proper classification:

```bash
npx astryx gap-report --list-categories

```

This outputs identifiers such as **Component**, **Documentation**, **UX**, and **Accessibility**. As documented in [`packages/cli/README.md`](https://github.com/facebook/astryx/blob/main/packages/cli/README.md) (lines 64-66), this flag queries the category registry established during command initialization.

### Submitting a Report Interactively

Run the base command to start the interactive session:

```bash
npx astryx gap-report

```

The CLI prompts you through:
1. **Category selection** (from the predefined list)
2. **Component identification** (e.g., Button, Card, Modal)
3. **Description** of the missing functionality
4. **Reproduction steps**, URLs, or screenshot references
5. **Confirmation** before submission

If `gapReport.url` is configured in `astryx.config.mjs`, the tool submits the data immediately. Otherwise, it follows the default behavior defined in the command implementation.

## Automating Gap Reports in CI/CD

For continuous integration pipelines or automated testing workflows, you can bypass the interactive prompts using flag-based arguments.

### Using the JSON API for Programmatic Access

The `gap-report` command supports machine-readable output via the `--json` flag. Query available categories programmatically with:

```bash
npx astryx --json gap-report --list-categories

```

The response conforms to the `gap-report.categories` type defined in the JSON API table in [`packages/cli/README.md`](https://github.com/facebook/astryx/blob/main/packages/cli/README.md) (lines 60-63), returning an array of category strings suitable for downstream tooling.

Submit non-interactive reports by specifying all required fields as flags:

```bash
npx astryx gap-report \
  --category Component \
  --component Button \
  --description "Missing gap prop for vertical stacks" \
  --url "https://github.com/facebook/astryx/issues/1234" \
  --no-interactive

```

This approach is registered in the CLI runtime through `apps/sandbox/scripts/generate-cli-registry.mjs`, which exposes the command's argument schema to the parser.

## Handling Failures and Error Codes

When gap report submission fails—whether due to missing URL configuration or remote service errors—the CLI returns a stable exit code that scripts can detect.

The command exits with code `ERR_GAP_REPORT_FAILED` when:
- No `gapReport.url` is configured and local storage fails
- The configured endpoint returns a non-2xx status code
- Network connectivity issues prevent transmission

This error code is documented in the error-code table in [`packages/cli/README.md`](https://github.com/facebook/astryx/blob/main/packages/cli/README.md) (lines 62-65), allowing CI pipelines to branch logic based on submission success or failure.

## Summary

- **Configuration**: Add a `gapReport` section to `astryx.config.mjs` to route reports to custom endpoints, as shown in [`packages/cli/README.md`](https://github.com/facebook/astryx/blob/main/packages/cli/README.md) (lines 32-40).
- **Interactive workflow**: Use `npx astryx gap-report` to launch a guided prompt for categorizing and describing missing features.
- **Automation**: Append `--json` for machine-readable output or use `--no-interactive` with specific flags to file reports from CI/CD pipelines.
- **Error handling**: Watch for exit code `ERR_GAP_REPORT_FAILED` to detect submission failures in automated environments.
- **Registration**: The command is registered in `apps/sandbox/scripts/generate-cli-registry.mjs` and documented in the CLI README.

## Frequently Asked Questions

### What is the gap-report command in Astryx?

The `gap-report` command is a built-in CLI tool in the Astryx design system that captures missing functionality, undocumented behavior, or UX inconsistencies. According to the source code in [`packages/cli/README.md`](https://github.com/facebook/astryx/blob/main/packages/cli/README.md), it supports both interactive prompts and programmatic JSON output to integrate with various development workflows.

### How do I configure a custom endpoint for gap reports?

Add a `gapReport` object with a `url` property to your `astryx.config.mjs` file. When configured, the CLI automatically POSTs report data to this endpoint. If omitted, the command defaults to local storage or generating a GitHub issue template.

### Can I file gap reports without user interaction?

Yes. Use the `--no-interactive` flag combined with `--category`, `--component`, and `--description` arguments to submit reports from scripts or CI pipelines. The `--json` flag also enables machine-readable output for category listings and submission confirmations.

### What error codes does the gap-report command return?

The command returns `ERR_GAP_REPORT_FAILED` when it cannot successfully submit the report, whether due to missing configuration, network errors, or remote service failures. This stable exit code is defined in [`packages/cli/README.md`](https://github.com/facebook/astryx/blob/main/packages/cli/README.md) (lines 62-65) and allows automated systems to handle submission failures gracefully.