test(expo): check native module specs against the shipped binary surface by mikepitre · Pull Request #10284 · clerk/javascript

mikepitre · 2026-10-16T19:18:47Z

Description

An Expo app can get new JavaScript over the air while the user keeps the app they installed from the store. So our new JS often runs on top of an older native build. If the JS calls a native function that build doesn't have, or passes it a different number of arguments, the app breaks. #8920 and #9373 both did this.

This adds a test that catches it before merge. It covers @clerk/expo-native-components, @clerk/expo-google-signin and @clerk/expo-biometrics on iOS and Android.

For each native function, the test looks at the Swift and Kotlin code in every stable release of that package, read from its git tag, and checks:

A function every release has must keep the same number of arguments. To change it, add a new function next to it.
A function some release lacks must be optional (?) in the TypeScript spec, so callers have to check for it first.
The spec matches the Swift and Kotlin code on this branch.

For example, #9373 needed to pass proxyUrl to native. Adding a third argument to configure breaks every app built on an older release, and the test now fails on it. What it does instead is keep configure and add an optional configureWithOptions:

if (ClerkExpo.configureWithOptions) {
  await ClerkExpo.configureWithOptions(publishableKey, token, { proxyUrl })
} else {
  await ClerkExpo.configure(publishableKey, token)
}

Adding a brand new native function works the same way: mark it ? in the spec and call it with ?..

Nothing needs updating after a release, because the test reads the tags each time it runs. CI now fetches those tags. If one is missing, the test fails and prints the git fetch command for it.

Run against the code from #8920 and #9373, the test fails and names the releases each change would break. It passes on this branch.

This also fixes stale paths in packages/expo/AGENTS.md, which still pointed at native code that moved into the three packages above. expo-passkeys isn't covered: it has no typed spec, and its iOS and Android functions differ on purpose.

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

🤖 Generated with Claude Code

…hipped binary surface The shipped surface in shipped-native-api.json comes from the latest release tags. Regenerate it with node packages/expo/scripts/generate-shipped-native-api.mjs after a release. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

vercel · 2026-10-16T19:18:51Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
clerk-js-sandbox	Ready	Preview	Oct 16, 2026 8:03pm UTC
swingset	Ready	Preview	Oct 16, 2026 8:03pm UTC

changeset-bot · 2026-10-16T19:18:53Z

🦋 Changeset detected

Latest commit: 9356b1e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

coderabbitai · 2026-10-16T19:18:57Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)
Review profile: ASSERTIVE
Plan: Team
Run ID: 588f8a10-fe65-4ea3-b1ab-0b13772663f7

📥 Commits

Reviewing files that changed from the base of the PR and between 2e01895 and 9356b1e.

📒 Files selected for processing: 2

packages/expo/src/specs/__tests__/nativeContract.test.ts
packages/expo/src/specs/__tests__/nativeModuleContract.ts

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

clerk/clerk_go (manual)
clerk/dashboard (manual)
clerk/accounts (manual)
clerk/backoffice (manual)
clerk/clerk (manual)
clerk/clerk-docs (manual)
clerk/cloudflare-workers (manual)
clerk/clerk-android (auto-detected)
clerk/clerk-ios (auto-detected)
clerk/cli (auto-detected)

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 2 remain after this review.

📝 Walkthrough

The changes add utilities that parse native function declarations and TypeScript specs, then compare them with current native implementations and source from matching release tags. A parameterized test checks each configured module. The CI workflow fetches matching release tags before unit tests run. The native-code guidance scope and a changeset file also change.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 9356b

No actionable issue remains from the reviewed release-tag checks; the change is mergeable after normal checks.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 2 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Description check		The description clearly explains the native module contract tests, the covered Expo packages, the compatibility checks, and the CI tag-fetch changes.
Title check		The title concisely and accurately describes the main change: testing Expo native module specs against the shipped native binary surface.

Fix all pre-merge checks with AI

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

pkg-pr-new · 2026-10-16T19:20:57Z

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@10284

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@10284

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@10284

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@10284

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@10284

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@10284

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@10284

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@10284

@clerk/expo-biometrics

npm i https://pkg.pr.new/@clerk/expo-biometrics@10284

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@10284

@clerk/expo-native-components

npm i https://pkg.pr.new/@clerk/expo-native-components@10284

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@10284

@clerk/express

npm i https://pkg.pr.new/@clerk/express@10284

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@10284

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@10284

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@10284

@clerk/mosaic

npm i https://pkg.pr.new/@clerk/mosaic@10284

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@10284

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@10284

@clerk/react

npm i https://pkg.pr.new/@clerk/react@10284

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@10284

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@10284

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@10284

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@10284

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@10284

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@10284

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@10284

commit: 9356b1e

The contract test now reads each native module from the latest @clerk/expo-native-components, @clerk/expo-google-signin and @clerk/expo-biometrics release tag with git, instead of a committed JSON snapshot that had to be regenerated after every release. If a tag is missing, the test fails and prints the git fetch command for it. The unit-test job checks out with depth 1 and no tags, so it now fetches those tags shallowly before the tests run. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

github-actions · 2026-10-16T19:54:44Z

API Changes Report

Generated by Break Check on 2026-10-16T20:05:56.043Z

Summary

Metric	Count
Packages analyzed	20
Packages with changes	0
🔴 Breaking changes	0
🟡 Non-breaking changes	0
🟢 Additions	0

No API Changes Detected

All packages have stable APIs with no detected changes.

Report generated by Break Check

_{Last ran on 9356b1e.}

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

mikepitre and others added 2 commits October 16, 2026 15:17

docs(expo): point AGENTS.md at the packages that hold the native code

65be013

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

github-actions Bot added the expo label Oct 16, 2026

vercel Bot deployed to Preview – clerk-js-sandbox October 16, 2026 19:19

View deployment

vercel Bot deployed to Preview – swingset October 16, 2026 19:21

View deployment

github-actions Bot added the actions label Oct 16, 2026

vercel Bot deployed to Preview – clerk-js-sandbox October 16, 2026 19:45

View deployment

vercel Bot deployed to Preview – swingset October 16, 2026 19:46

View deployment

mikepitre marked this pull request as ready for review October 16, 2026 19:50

mikepitre requested a review from wobsoriano October 16, 2026 19:51

test(expo): check the native contract against every stable release

9356b1e

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

vercel Bot deployed to Preview – clerk-js-sandbox October 16, 2026 20:01

View deployment

vercel Bot deployed to Preview – swingset October 16, 2026 20:03

View deployment

Navigation Menu

Repository navigation

test(expo): check native module specs against the shipped binary surface - #10284

test(expo): check native module specs against the shipped binary surface#10284
mikepitre wants to merge 4 commits into
mainfrom
test/expo-native-contract

mikepitre commented Oct 16, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Oct 16, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Oct 16, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Oct 16, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Oct 16, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 16, 2026 •

edited

Loading

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

mikepitre commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Type of change

Uh oh!

vercel Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

coderabbitai Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

API Changes Report

Summary

No API Changes Detected

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

mikepitre commented Oct 16, 2026 •

edited

Loading

vercel Bot commented Oct 16, 2026 •

edited

Loading

changeset-bot Bot commented Oct 16, 2026 •

edited

Loading

coderabbitai Bot commented Oct 16, 2026 •

edited

Loading

pkg-pr-new Bot commented Oct 16, 2026 •

edited

Loading

github-actions Bot commented Oct 16, 2026 •

edited

Loading