facebook / facebook/astryx

feat(cli): expose findRelatedBlocks through the public API

Open
#1,901 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
TypeScript
Stars
13.1k
Forks
1.1k
Avg merge
1d 14h
Merged PRs (30d)
669

Description

## Problem

When building the docsite component detail page, we needed to fetch example blocks (non-showcase) for each component. The CLI has `findRelatedBlocks(componentName)` in `template.mjs` which does exactly this, but it is not re-exported from `@xds/cli/api`.

## Friction encountered

1. **`findRelatedBlocks` exists but is not accessible** — it is exported from `template.mjs` but the API index (`api/index.mjs`) only re-exports `template()`. Direct subpath imports fail because the `exports` field in `package.json` restricts access to `./api` and `./json` only.

2. **`template()` list does not include enough metadata** — the list endpoint returns `name`, `displayName`, `description`, `isReady`, `type` but not `category`, `isShowcase`, `componentsUsed`, or any way to associate blocks with components.

3. **No `component(name, { blocks: true })` option** — there is `component(name, { showcase: true })` which internally calls `findShowcase`, but no equivalent for fetching related example blocks.

4. **Workaround required filesystem reads** — we ended up reading directly from `node_modules/@xds/cli/templates/blocks/components//` and regex-parsing the `.doc.mjs` files for metadata. This works but is fragile and bypasses the CLI abstraction.

## Proposed solution

Add one or both of:

### Option A: Export `findRelatedBlocks` from the API
```js
// api/index.mjs
export { findRelatedBlocks } from './template.mjs';
```

### Option B: Add a `blocks` option to the `component()` API
```js
const result = await component('Button', { blocks: true });
// { type: 'component.detail.blocks', data: [{ id, name, description, source, isShowcase }] }
```

Option B is cleaner since it follows the existing pattern (`showcase: true` → showcase data), and could filter out showcases by default (with an opt-in to include them).

## Additional note

The `template()` list endpoint would also benefit from including `category` and `componentsUsed` fields, which would allow client-side filtering without additional API calls.

Contributor guide

Open the contributing guide

Research direction

Read api/index.mjs and template.mjs to compare the existing template() and component(..., { showcase: true }) API paths, then inspect package.json exports for the public subpaths. Decide which proposed related-blocks API fits the existing pattern, and verify that it can be imported through @xds/cli/api with the requested block metadata and filtering behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, cli
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
58/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.