Ship 0.9.1: sealed surface (no extra items shared in build folder) and more aligned/connected package README docs by cameronapak · Pull Request #83 · youversion/platform-sdk-reactnative-expo

cameronapak · 2026-07-14T15:46:55Z

Note

✅ I want to get #85 in before this PR

Warning

Merging this PR publishes 0.9.1 to npm immediately — zero pending changesets + an unpublished version puts the release workflow on its publish path. Don't close PR #63; the changesets action resolves it once main has no changesets.

Summary

Ships both packages as 0.9.1 — the first release with real changelogs — by replacing the nine pending changesets with curated initial-release notes and sealing the import surface to the package root before anyone can depend on internals.

Changes

Both packages release as 0.9.1 with curated initial-release changelogs: the nine pending changesets are deleted, their user-relevant content (prop-type exports, showVersionPicker default, iPad sheet width cap, auth hardening) folded in, and pre-release polish dropped as fixes to a release that never shipped.
Consumers can only import the package root — root-only exports maps in both packages (src/ in dev, swapped to build/ at publish via publishConfig.exports); deep imports like build/dom/* stop resolving under Node and fail typecheck. (this makes it where people cannot depend on package internals that they don't need to use)
The npm package pages cross-link each other and point to the platform dev docs (developers.youversion.com/sdks/react-native) instead of the GitHub repo — READMEs restructured to match the react SDK's package READMEs.
Running pnpm build locally no longer starts a tsc watcher (root build runs expo-module build with CI=true).
ADR 0011 and CONTEXT.md document the sealed import surface, including its enforcement boundary.
DEFAULT_BIBLE_VERSION_ID is no longer exported (review feedback: the SDK shouldn't publish an official default). It stays internal as the default for BibleCard / BibleReader / the picker sheets; README examples pass 3034 literally.

Start here: change 2 — Metro (even with package exports on) falls back to filesystem resolution for unmatched subpaths, so the seal is enforced by TypeScript and Node resolution, not physically by the RN bundler. ADR 0011 records this honestly.

Test plan

pnpm typecheck / pnpm test (309 tests) / pnpm build green; full CI (including Greptile) green on head 0271c53
pnpm pack tarballs installed in a scratch project: root import resolves to build/index.js; types resolve under moduleResolution: node16 and bundler; deep import throws ERR_PACKAGE_PATH_NOT_EXPORTED; 'use dom' is line 1 of build/dom/*.js; publishConfig.exports confirmed applied in the packed package.json
apps/example Metro iOS bundle succeeds with the new exports field
Device E2E: fresh Expo SDK 56 app built only from the packed tarballs renders VerseOfTheDay (Revelation 3:20 BSB) and BibleTextView (John 3:16) on an iOS simulator — retires PUBLISHING.md's first-publish device gate
changeset status confirms zero pending changesets (ui → core stays workspace:*; changeset version was not run)
README checks: prettier --check passes; docs page verified live; cross-links use absolute npm URLs (repository.directory is set, so relative ./LICENSE / ./package.json links resolve on npm)

🤖 Generated with Claude Code

Greptile Summary

This PR prepares the SDK packages for the 0.9.1 npm release. The main changes are:

Root-only package exports for core and UI.
Updated package versions, changelogs, and npm READMEs.
Removed the public UI default Bible version constant.
Release workflow and build script updates.
Documentation for the sealed import surface and publish behavior.

Confidence Score: 5/5

This looks safe to merge.

No blocking issues found in the changed code.

Important Files Changed

Filename	Overview
packages/ui/package.json	Adds root-only exports for the UI package and matching publish-time build entry points.
packages/core/package.json	Adds root-only exports for the core package and matching publish-time build entry points.
packages/ui/src/index.ts	Removes the default Bible version constant from the public UI barrel while leaving internal defaults in place.
.github/workflows/release.yml	Updates the publish workflow comments and relies on pnpm for the registry publish path.
README.md	Updates root usage examples to use literal Bible version IDs.
packages/ui/README.md	Reworks the UI package README for npm-focused install, usage, and docs links.
packages/core/README.md	Reworks the core package README for npm-focused install, auth usage, and docs links.
docs/adr/0011-compiled-distribution.md	Documents the sealed package surface and the Metro enforcement boundary.

_{Reviews (9): Last reviewed commit: "ci: drop the inert npm upgrade from the ..." | Re-trigger Greptile}

Context used (10)

Context used - AGENTS.md (source)
Context used - CLAUDE.md (source)
File used - docs/contributing/native-i18n.md (source)
File used - packages/ui/src/i18n/locales/en.json (source)
File used - packages/ui/src/i18n/locales/es.json (source)
File used - packages/ui/src/i18n/locales/fr.json (source)
File used - packages/ui/src/i18n/locales/index.ts (source)
File used - docs/adr/0008-sdk-owned-i18next-no-consumer-overrides.md (source)
File used - docs/adr/0009-deferred-dom-localization.md (source)
File used - docs/adr/0007-app-locale-vs-bible-language-id.md (source)

jhampton

Responded to some of David's comments for context, but overall this LGTM for our 0.9.1

Fold API-relevant changeset content into the curated 1.0.0 CHANGELOG entries and remove the nine pending changesets. Both packages stay at 1.0.0 (unpublished), so everything ships as the initial release. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

trigger HMR

Add a root-only `exports` map to both packages so consumers can only import from the package root (`@youversion/platform-react-native-expo-ui` and `-core`). Deep imports into internal build files (e.g. `.../build/dom/bible-card`) are no longer supported: Node resolution and TypeScript reject them, keeping the internal file layout non-API before the first real release (0.9.1). - exports["."] -> src/index.ts for dev; publishConfig.exports swaps to build/index.js + build/index.d.ts at publish (verified applied in the pnpm pack tarball). `./package.json` stays exposed. - ADR 0011 gains a "Sealed import surface" section, including the enforcement boundary: Node and TypeScript enforce the seal strictly, Metro does not (it falls back to filesystem resolution for unmatched subpaths even with unstable_enablePackageExports on). - CONTEXT.md and both CHANGELOGs note the sealed root-only surface. Verified: typecheck/test/build green; tarball root import resolves to build/index.js, types resolve under node16 + bundler, deep imports throw ERR_PACKAGE_PATH_NOT_EXPORTED; example app and a fresh SDK 56 app built from the tarballs both bundle; the fresh app renders real Bible content (VerseOfTheDay + BibleTextView) on an iOS simulator. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Un-export DEFAULT_BIBLE_VERSION_ID per review: the constant stays internal as the default for BibleCard/BibleReader/picker sheets, but the SDK no longer publishes an official default version id. README examples pass 3034 literally instead. Also applies the reviewed copy edits to the package READMEs and the UI changelog. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Per review: the installation id is automatic and doesn't warrant a "when you need this package" bullet. It stays mentioned in the intro line. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

PR #85 landed on main with a pending changeset. Consuming it here keeps .changeset/ empty, which is what makes the release workflow publish on merge instead of opening a "Version Packages" PR. The attribution behavior is folded into the 0.9.1 UI changelog as part of the initial release rather than as a fix, since there is no prior release to have regressed from. Core is untouched — the changeset marked UI only. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The ADR documented the stamp's fail-closed guard but was silent on what happens when a release is retried, leaving the guard's "refuses to re-stamp" behavior to read as a retry hazard. It isn't one. `expo-module prepublishOnly` is `expo-module clean && expo-module build`, so `build/` is regenerated from source — anchor back at `= false` — before the stamp runs. A retried release meets exactly one anchor again rather than the `= true` file from the previous attempt. The transform stays deliberately non-idempotent: it throws `found 0` on already-stamped input, and nothing on the publish path reaches the stamp without a rebuild in front of it. That distinction is what the ADR was missing. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

PR #86 landed on main with a pending changeset. Consuming it here keeps .changeset/ empty, which is what makes the release workflow publish on merge instead of opening a "Version Packages" PR. The pinning is folded into the 0.9.1 UI changelog as a durable property of the package surface rather than as a change, since there is no prior release to have pinned differently. Core is untouched — the changeset marked UI only. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The "Update npm to latest version" step claimed trusted publishing needed npm >= 11.5, or the OIDC handshake would silently fall back to NPM_TOKEN. That mechanism does not exist on this path. `changeset publish` shells out to `pnpm publish`, and pnpm 11 publishes over HTTP itself and runs the OIDC handshake in its own code. There is no `runNpm` on pnpm 11's publish path at all, so the npm on the runner never sees the token and its version cannot affect auth. npm is still invoked once per package for `npm info`, a read-only metadata query that any npm handles, so removing the global upgrade is safe. Correct the surrounding comments to match, since a misleading comment on the first CI publish sends whoever debugs it chasing a dead mechanism: - Describe the OIDC handshake as pnpm's rather than npm's. - Keep NPM_CONFIG_PROVENANCE as an explicit no-op. pnpm reads PNPM_CONFIG_* and ignores it; provenance is auto-enabled by pnpm's OIDC path for public repos on GitHub Actions. That last part is read from pnpm's source, not observed, so the var stays until a real run proves it redundant. - Fix the NODE_AUTH_TOKEN fallback, which as written would not have worked. pnpm never reads NODE_AUTH_TOKEN; it only arrives via an .npmrc, which actions/setup-node writes only when given a `registry-url`, and our setup action does not set one. Document both halves the fallback needs. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

jhampton

Just comments. Approved.

cameronapak changed the title ~~chore: consolidate pending changesets into 1.0.0 initial release~~ chore: consolidate pending changesets into 0.9.1 initial release Jul 14, 2026

cameronapak force-pushed the claude/sdk-version-consolidation-c02a87 branch from 52bd567 to 1765f8e Compare July 14, 2026 16:01

cameronapak changed the title ~~chore: consolidate pending changesets into 0.9.1 initial release~~ Ship 0.9.1: consolidated changelogs, sealed import surface Jul 14, 2026

cameronapak changed the title ~~Ship 0.9.1: consolidated changelogs, sealed import surface~~ Ship 0.9.1: clean history, sealed surface, honest docs Jul 14, 2026

cameronapak requested review from davidfedor and jhampton July 14, 2026 20:15

cameronapak changed the title ~~Ship 0.9.1: clean history, sealed surface, honest docs~~ Ship 0.9.1: sealed surface (no extra items shared in build folder) and honest docs Jul 14, 2026

cameronapak changed the title ~~Ship 0.9.1: sealed surface (no extra items shared in build folder) and honest docs~~ Ship 0.9.1: sealed surface (no extra items shared in build folder) and more aligned/connected package README docs Jul 14, 2026

cameronapak requested a review from Dustin-Kelley July 14, 2026 20:23

cameronapak self-assigned this Jul 14, 2026

davidfedor requested changes Jul 14, 2026

View reviewed changes

jhampton approved these changes Jul 15, 2026

View reviewed changes

Comment thread packages/core/README.md

Comment thread packages/ui/README.md Outdated

cameronapak force-pushed the claude/sdk-version-consolidation-c02a87 branch from 937c1fb to 3007299 Compare July 16, 2026 17:28

cameronapak and others added 11 commits July 16, 2026 12:36

chore: release as 0.9.1 instead of 1.0.0

3ed230e

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Fix: This makes it where running the build script locally doesn't

64decde

trigger HMR

docs: package READMEs cross-link and point to dev docs

6bdf39c

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs: import Text in core README snippet

4aaa8b9

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs: drop installation id bullet from core README

56370d5

Per review: the installation id is automatic and doesn't warrant a "when you need this package" bullet. It stays mentioned in the intro line. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

cameronapak force-pushed the claude/sdk-version-consolidation-c02a87 branch from 3007299 to fbaf002 Compare July 16, 2026 17:58

cameronapak requested review from davidfedor and jhampton July 16, 2026 19:46

davidfedor approved these changes Jul 16, 2026

View reviewed changes

jhampton approved these changes Jul 17, 2026

View reviewed changes

Comment thread README.md

Comment thread packages/core/package.json

cameronapak merged commit 9f1eaf9 into main Jul 17, 2026
7 checks passed

cameronapak mentioned this pull request Jul 17, 2026

Do not ship (#83 will do this) -> chore: version packages #63

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Ship 0.9.1: sealed surface (no extra items shared in build folder) and more aligned/connected package README docs#83

Ship 0.9.1: sealed surface (no extra items shared in build folder) and more aligned/connected package README docs#83
cameronapak merged 12 commits into
mainfrom
claude/sdk-version-consolidation-c02a87

cameronapak commented Jul 14, 2026 •

edited by greptile-apps Bot

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jhampton left a comment

Uh oh!

Uh oh!

Uh oh!

jhampton left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

cameronapak commented Jul 14, 2026 • edited by greptile-apps Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Test plan

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Context used (10)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jhampton left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

jhampton left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

cameronapak commented Jul 14, 2026 •

edited by greptile-apps Bot

Loading