Skip to content

Commit 8b1728b

Browse files
committed
ci: check the public type surface with api-extractor
4.2.4 shipped a breaking type change as a patch. ObservableStatus<T> went from a flat interface to a discriminated union, so data became T | undefined and the documented destructure-and-use pattern stopped compiling for strict-TS consumers. Nothing in the release flow compared the published type surface, so it went out unnoticed. api-extractor generates etc/reactfire.api.md, a report of every public export. CI regenerates it and fails when it no longer matches, so a change to the type surface shows up as a reviewable diff in the pull request instead of being discovered by a consumer after release. The report is generated by npm run api:report and never hand-edited. Nothing here is maintained by hand. Verified against a faithful reproduction of 4.2.4, patched so only consumers break rather than internals: plain tsc still passes, and api:check exits 1 with a one-line diff, data: T becoming T | undefined. Two notes for review: api-extractor bundles TypeScript 5.9.3 and this repo is on 6.0.3, so it prints a version warning on every run. The emitted .d.ts contain no TypeScript 6 only syntax, and the report reproduces the emitted signatures exactly, so the older engine has nothing to misparse. Worth rechecking if the public surface ever adopts newer syntax. The job builds with vite, not tsc. tsconfig.json sets noEmit, so tsc is a type check only; @rollup/plugin-typescript inside the vite build is what emits the declarations api-extractor reads. Closes #749
1 parent 0b90534 commit 8b1728b

6 files changed

Lines changed: 883 additions & 2 deletions

File tree

‎.github/workflows/test.yaml‎

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,34 @@ jobs:
8282
run: npm run lint:types -- reactfire-${{ github.run_id }}/reactfire.tgz
8383
- name: Bundle size
8484
run: npm run size
85+
check-api:
86+
runs-on: ubuntu-latest
87+
name: Check API surface
88+
steps:
89+
- name: Checkout
90+
uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
91+
with:
92+
persist-credentials: false
93+
- name: Setup node
94+
uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
95+
with:
96+
node-version: '24'
97+
cache: 'npm'
98+
- name: Install deps
99+
run: npm ci
100+
# vite build, not tsc: tsconfig.json sets noEmit, so tsc is a type check
101+
# only. @rollup/plugin-typescript inside the vite build is what emits the
102+
# declarations api-extractor reads.
103+
- name: Build declarations
104+
run: npx vite build
105+
# Fails when the emitted public type surface no longer matches the
106+
# committed report in etc/. The report is generated (npm run api:report)
107+
# and never hand-edited, so a type change shows up as a reviewable diff in
108+
# the pull request. Needs no network and no published release to compare
109+
# against, which is what 4.2.4 lacked when it shipped a breaking type
110+
# change as a patch (#749).
111+
- name: API report
112+
run: npm run api:check
85113
test:
86114
runs-on: ubuntu-latest
87115
needs: build
@@ -152,7 +180,7 @@ jobs:
152180
publish:
153181
runs-on: ubuntu-latest
154182
name: Publish (NPM)
155-
needs: [test, verify-package]
183+
needs: [test, verify-package, check-api]
156184
if: ${{ github.ref == 'refs/heads/main' || github.event_name == 'release' }}
157185
steps:
158186
- name: Setup node

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,3 +29,6 @@ unpack.sh
2929
example/.parcel-cache/
3030
.firebaserc
3131
stats.html
32+
33+
# api-extractor scratch output
34+
temp/

‎api-extractor.json‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
{
2+
"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
3+
4+
// Runs against the emitted declarations, not src, so what is reported is what
5+
// consumers actually resolve.
6+
"mainEntryPointFilePath": "<projectFolder>/dist/index.d.ts",
7+
8+
"compiler": {
9+
"tsconfigFilePath": "<projectFolder>/tsconfig.json"
10+
},
11+
12+
// The committed report is the whole point: a change to the public type surface
13+
// shows up as a diff in review, and CI fails when the report is out of date.
14+
// Generated, never hand-edited.
15+
"apiReport": {
16+
"enabled": true,
17+
"reportFolder": "<projectFolder>/etc/",
18+
"reportFileName": "reactfire.api.md"
19+
},
20+
21+
"docModel": { "enabled": false },
22+
"dtsRollup": { "enabled": false },
23+
"tsdocMetadata": { "enabled": false },
24+
25+
"messages": {
26+
// Missing release tags are not interesting here; the repo does not use them.
27+
"extractorMessageReporting": {
28+
"ae-missing-release-tag": { "logLevel": "none" },
29+
"ae-forgotten-export": { "logLevel": "warning" }
30+
},
31+
"tsdocMessageReporting": {
32+
"default": { "logLevel": "none" }
33+
}
34+
}
35+
}

0 commit comments

Comments
 (0)