feat(cli): expose findRelatedBlocks through the public API
- 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
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