build(core): Add public API surface tracking with api-extractor

.github/workflows/buildandtest.yml

@@ -311,6 +311,31 @@ jobs:
       - name: Run madge
         run: yarn circularDepCheck
 
+  job_api_report:
+    name: API Report Check
+    runs-on: ["ghcr.io/cirruslabs/ubuntu-runner-amd64:24.04", "runner_group_id:10"]
+    needs: [job_build, diff_check]
+    if: ${{ needs.diff_check.outputs.skip_ci != 'true' }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - run: corepack enable
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+        with:
+          package-manager-cache: false
+          node-version: 18
+          cache: 'yarn'
+          cache-dependency-path: yarn.lock
+      - name: Install Dependencies
+        run: yarn install
+      - name: Download dist
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: packages/core/dist
+      - name: Check API Report
+        working-directory: packages/core
+        run: yarn api-report:check
+
   job_bundle:
     name: Bundle
     runs-on: ["ghcr.io/cirruslabs/ubuntu-runner-amd64:24.04", "runner_group_id:10"]

.gitignore

@@ -88,6 +88,9 @@ node_modules.bak
 !.yarn/plugins
 .pnp.*
 
+# API Extractor temp files
+/packages/core/temp/
+
 # Sentry React Native Monorepo
 /packages/core/README.md
 .env.sentry-build-plugin

AGENTS.md

@@ -24,6 +24,8 @@ yarn build
 | Run all linters | `yarn lint` |
 | Auto-fix lint | `yarn fix` |
 | Circular dep check | `yarn circularDepCheck` |
+| API report generate | `yarn api-report` |
+| API report check | `cd packages/core && yarn api-report:check` |
 | TS/JS lint | `yarn lint:lerna` |
 | Android lint | `yarn lint:android` |
 | Kotlin lint | `yarn lint:kotlin` |
@@ -62,6 +64,7 @@ When asked to open a PR:
 - [ ] All tests pass (`yarn test`)
 - [ ] Linting passes (`yarn lint`)
 - [ ] No circular dependencies (`yarn circularDepCheck`)
+- [ ] API report up to date (`yarn api-report` after `yarn build:sdk`)
 - [ ] Native code formatted correctly
 - [ ] TypeScript types are correct
 - [ ] Tests added/updated for changes
@@ -72,7 +75,7 @@ Workflows in `.github/workflows/`:
 
 | Workflow | Purpose |
 |----------|---------|
-| `buildandtest.yml` | TS compilation, Jest tests, linting, circular dep check, TS 3.8 compat |
+| `buildandtest.yml` | TS compilation, Jest tests, linting, circular dep check, API report, TS 3.8 compat |
 | `native-tests.yml` | iOS/Android native tests across RN versions |
 | `e2e-v2.yml` | E2E tests with Maestro on Sauce Labs |
 | `sample-application.yml` | Sample RN app builds (iOS, Android, old/new arch) |

CONTRIBUTING.md

@@ -40,6 +40,19 @@ cd packages/core
 yarn test:watch
 ```
 
+## Public API Changes
+
+We track the public API surface using [@microsoft/api-extractor](https://api-extractor.com/). A baseline report is committed at `packages/core/etc/sentry-react-native.api.md`. CI will fail if the public API changes without updating this file.
+
+If your change modifies the public API (new exports, changed signatures, removed APIs):
+
+```sh
+yarn build:sdk
+yarn api-report
+```
+
+Review the diff in `packages/core/etc/sentry-react-native.api.md` and commit the updated report alongside your code changes.
+
 ## Running the sample
 
 First, set up the Sentry CLI token.

package.json

@@ -25,7 +25,8 @@
     "swift:lint": "./scripts/swiftlint.sh",
     "run-ios": "cd samples/react-native && yarn react-native run-ios",
     "run-android": "cd samples/react-native && yarn react-native run-android",
-    "set-version-samples": "lerna run set-version"
+    "set-version-samples": "lerna run set-version",
+    "api-report": "yarn workspace @sentry/react-native api-report:generate"
   },
   "devDependencies": {
     "@naturalcycles/ktlint": "^1.13.0",

packages/core/api-extractor.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "mainEntryPointFilePath": "<projectFolder>/dist/js/index.d.ts",
+  "bundledPackages": ["react-native"],
+  "compiler": {
+    "tsconfigFilePath": "<projectFolder>/tsconfig.api-extractor.json"
+  },
+  "apiReport": {
+    "enabled": true,
+    "reportFolder": "<projectFolder>/etc/",
+    "reportFileName": "sentry-react-native.api.md"
+  },
+  "docModel": {
+    "enabled": false
+  },
+  "dtsRollup": {
+    "enabled": false
+  },
+  "tsdocMetadata": {
+    "enabled": false
+  },
+  "messages": {
+    "extractorMessageReporting": {
+      "ae-missing-release-tag": { "logLevel": "none" }
+    },
+    "compilerMessageReporting": {
+      "default": { "logLevel": "warning" }
+    },
+    "tsdocMessageReporting": {
+      "default": { "logLevel": "none" }
+    }
+  }
+}