What's the use of public-api.ts in Angular Material/ Angular Flex Layout?

Question

I learned from angular-material and angular-flex-layout that when they export a component, they first export the relevant sub-components in public-api.ts and then just export everything from the public-api.ts in the index.ts (e.g. export * from './public-api'). Here is the example of its badge component:

// public-api.ts export * from './badge-module'; export * from './badge';

// index.ts export * from './public-api';

My question is why don't just put all the export things to index.ts but border to create one more public-api.ts?

Answer 1

To keep the code cleaner.

Because 'index' doesn't mean much. But 'public-api' makes it clear what is there, that is, public entities

public_api.ts is intended to enumerate and expose specific functionality for external use. index.ts is intended as a default exporting mechanism to deprecate full-path imports.

Using public_api.ts in libraries instead of piling everything in index.ts

Answer 2

At a glance I think there are several reasons:

1. Disambiguation: Given the lack of an "internal" modifier and the complexity added by internal modules, more than one index.ts barrel file is required to offer distinct internal/external API surfaces.
2. Angular CLI user-facing tooling: To offer low-effort tooling defaults, a public API file standard was required. The NG compiler does more than just builds all the TypeScript to JavaScript; notably it also tree-shakes depending on the entrypoint chosen. For other reasons here, index.ts was a poor choice for the default. See Creating Libraries.
3. Angular internal code quality: The public-api is the contract with Angular consumers and must be tightly controlled, with changes accompanied by documentation changes, new tests, compatibility evaluation, and announcements. To do so, project settings automatically reject code changes that result in changes to public-api. See Golden Files.
4. Awareness/Clarity/Intent: I think this is generally what the other comments have hinted at. People have historically been using index.ts for everything, both internal and external. Sure, a project could use index.ts only for public API signatures, but it wouldn't be obvious.