How to File Gap Reports for Missing Features in Astryx Components

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:

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

According to the CLI documentation in 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:

npx astryx gap-report --list-categories

This outputs identifiers such as Component, Documentation, UX, and Accessibility. As documented in 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:

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:

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 (lines 60-63), returning an array of category strings suitable for downstream tooling.

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

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 (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 (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, 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 (lines 62-65) and allows automated systems to handle submission failures gracefully.

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