This implements revamped build workflow and api-generation with stripping of APIs marked via @internal/@alpha/@beta JSDoc annotation.

💡NOTE:

• implementation affects only v9
• CHANGES IN THIS PR will have NO EFFECT on any v9 package as it is implemented with gradual migration enablement. To enable this new behaviours follow up set of PR's will be created that will invoke migrate-converged-pkg automation per package.

Current Behavior

Build tasks:

• build task doesn't uses path aliases
• build:local task uses path aliases

API-extractor configuration:

• we need to maintain 2 different configs for build and build:local, which tend to not work all the time ( react-components suite)
• we generate all api-extractor metadata that are not needed/used (api report, tsdoc metadata, dts rollup, doc model )

API Surface:

• api surface of an package is being shipped to npm as rolluped index.d.ts, which might expose APIs not intended to be used for consumers

New Behavior

Build tasks:

• build task uses path aliases
  • compiled output will be emitted to root dist instead of per package dist, afterwards assets are copied to package scope for publishing purposes
• build:local npm script task is replaced with generate-api task that uses path aliases

API-extractor configuration:

• we use only 1 api-extractor configuration which works for all use-cases
• we generate only api report and dts rollup via api-extractor

API Surface:

• apis marked as @internal/@alpha/@beta are removed from package API surface ( rolluped index.d.ts )
  • this protects us on tooling from exposing or even re-exporting from other package non public apis

Detailed workflow comparison

generating api.md file

BEFORE:

yarn workspace @fluentui/react-text build:local

🚨 No failures ever as there is no api trimming/validation

AFTER:

yarn workspace @fluentui/react-text generate-api

✅ This might fail in 2 scenarios:

1. dependant packages are missing generated index.d.ts file.

If this case occurs tooling will guide you with following DX:

2. your package is using non public API from dependant packages as a part of its PUBLIC API

NOTE:

• in some scenarios type information might be properly inlined so things will work
• re-exporting a non public API from other package will not be allowed and will throw an error

If this case occurs tooling will guide you with following DX:

🛠 Known issues:

• currently if you expose a non public API inside package it will generate invalid index.d.ts file. A follow up work will be done after this will be merged.
• 💁‍♂️ note: if such a scenario occurs ts-minbar-react-components will catch such an issue on CI

// @filename package-a/src/index.ts
/**
 * @internal
 */
export type InternalApi = {day: string}
export function hello(): InternalApi {...}
export function time():number {...}

⬇⬇⬇ tsc emit

// @filename package-a/dist/index.d.ts

// 🚨 InternalApi was removed - index.d.ts is invalid type declaration
export declare function hello(): InternalApi {...}
//                                                    ~~~~~~~~   
export declare function time():number {...}

Related Issue(s)

Fixes partially #23343