Manage API Extractor reports and release tag entry points in the Fluid Framework monorepo. Use when regenerating API reports, adding new exports, changing release tags, or debugging API Extractor errors. Triggers on mentions of API reports, api-extractor, release tags, entry points, public/beta/alpha/legacy/internal exports.
Instrucciones de origen · Vista previa de solo lectura
name
api-reports
description
Manage API Extractor reports and release tag entry points in the Fluid Framework monorepo. Use when regenerating API reports, adding new exports, changing release tags, or debugging API Extractor errors. Triggers on mentions of API reports, api-extractor, release tags, entry points, public/beta/alpha/legacy/internal exports.
API Report Management
Manage the API Extractor and release tag system in the Fluid Framework monorepo.
Overview
Every published package has:
Entry point files (public.d.ts, beta.d.ts, alpha.d.ts, legacy.d.ts) generated by flub generate entrypoints
API report files (.api.md) generated by api-extractor run that snapshot the public API surface
Lint configs that validate entry points are well-formed and release tags are consistent
The two-phase system works as follows:
Phase 1: flub generate entrypoints reads src/index.ts, filters by release tags, and writes filtered .d.ts files into lib/ and dist/
Phase 2: api-extractor run reads those .d.ts files and produces .api.md report snapshots
Release Tags
Apply these TSDoc tags to exported symbols in source code:
Tag
Visibility
Included In
@public
Stable, supported
public.d.ts, beta.d.ts, alpha.d.ts
@beta
Under development
beta.d.ts, alpha.d.ts
@alpha
Experimental
alpha.d.ts only
@legacy
Deprecated but maintained
legacy.d.ts
@internal
Not for external use
index.d.ts (internal entry point) only
@sealed
Cannot be extended/implemented
(modifier, used with above tags)
@system
Internal system types
Shown in reports for context
New APIs should typically start at @alpha or @beta, not @public.
Entry Points in package.json
The exports field maps subpaths to filtered type definitions:
Each path also has a require variant pointing to dist/ for CJS. The JS entry point is always index.js — only the type definitions differ per release level.
Not all packages expose all levels. Most expose . (public), ./internal, and ./legacy. Only packages with beta/alpha APIs add those paths.
src/alpha.ts — if needed, re-exports from index.ts with alpha-level filtering (rare, most packages just use tags)
src/legacy.ts — legacy exports (older API surface)
src/internal.ts — re-exports everything from index.ts (used by ./internal path)
Regenerating API Reports
After Changing Exports in a Package
cd packages/path/to/package
# Step 1: Build the package (generates .js and .d.ts in lib/ and dist/)
fluid-build . --task compile
# Step 2: Generate filtered entry points
npm run api-extractor:esnext # generates lib/public.d.ts, lib/beta.d.ts, etc.
npm run api-extractor:commonjs # generates dist/public.d.ts, dist/beta.d.ts, etc.# Step 3: Generate API reports
npm run build:api-reports # runs api-extractor for both current and legacy
Or use the single command:
fluid-build . --task api
Verify Entry Points Are Valid
npm run check:exports
This runs all lint configs (api-extractor-lint-public.esm.json, etc.) to validate each entry point.
API Report Files
Located in api-report/ within each package:
File
Content
<pkg>.public.api.md
Public API snapshot
<pkg>.beta.api.md
Public + beta API snapshot
<pkg>.alpha.api.md
Public + beta + alpha API snapshot
<pkg>.legacy.public.api.md
Legacy public API
<pkg>.legacy.beta.api.md
Legacy public + beta API
These files are committed to the repo. Changes to them in a PR indicate the public API surface has changed.
Reading Report Diffs
When .api.md files change in a PR:
Added lines = new APIs being exposed
Removed lines = APIs being removed (potential breaking change)
Changed signatures = API modification (check backward compatibility)
API Extractor Config Hierarchy
Each package has an api-extractor/ directory with configs that extend base configs:
