[turnipdabeets]

Problem

Part of the posthog-react-native 5.0 major (#5534). 5.0 changes the capture endpoint, removes deprecated options, plugin fallbacks and feature flag methods, and adds captureAi(). Apps upgrading need one place that lists what to change, like posthog-node 6's MIGRATION.md.

Changes

• Adds packages/react-native/MIGRATION.md: a checklist, then sections for reverse proxies and self-hosted PostHog, the native plugin, removed options, feature flags (onFeatureFlags, removed methods, payloads, hooks), event delivery and AI events, with before/after snippets.
• Links it from the RN README.

It documents the changes in #5701, #5703, #5702 and #5708, so it should merge into chore/rn-v5 after them; anything those PRs change before merging needs a matching edit here. The guide links to the plugin's MIGRATION.md from #5194.

Not covered yet: the posthog.com upgrade guide, which will be built from this.

Release info Sub-libraries affected

Libraries affected

• All of them
• posthog-js (web)
• posthog-js-lite (web lite)
• posthog-node
• posthog-react-native
• @posthog/react-native-plugin
• @posthog/react
• @posthog/ai
• @posthog/convex
• @posthog/next
• @posthog/nextjs-config
• @posthog/nuxt
• @posthog/openfeature-node-provider
• @posthog/openfeature-web-provider
• @posthog/rollup-plugin
• @posthog/webpack-plugin
• @posthog/types
• @posthog/browser-common

Docs only; MIGRATION.md isn't in the npm package, so there's no changeset.

Checklist

• All commits are signed (see Commit signing)
• Tests for new code
• Accounted for the impact of any changes across different platforms
• Accounted for backwards compatibility of any changes (no breaking changes!)
• Took care not to unnecessarily increase the bundle size

If releasing new changes

• Ran pnpm changeset to generate a changeset file

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

• Written with Claude Code from the five PRs' changesets and review notes. Claims were checked against the branches: getAllFeatureFlags() returns a list of results, fetchRetryCount isn't described as still applying elsewhere, and screenshotModeBackgroundCapture stays (feat(react-native)!: drop legacy replay plugin and deprecated config #5701 restored it).
• $locale isn't in the guide: RN already sends the first preferred language as a full tag (de-CH) through expo-localization or react-native-localize, matching posthog-ios 4.0. On Android with a per-app language it follows the app's language, while posthog-android 4.0 reports the device language; that's unchanged in 5.0.

[github-actions]

📝 No Changeset Found

This PR doesn't include a changeset. A changeset is required to release a new version.

How to add a changeset

Run this command and follow the prompts:

pnpm changeset

Remember: Never use major version bumps for posthog-js as it's autoloaded by clients.

[github-actions]

⚠️ `posthog-react-native` is modified but this PR has no changeset

This is informational — the PR is not blocked. Click the triangle above to collapse, or push a fix and this comment will auto-delete.

Modified in this PR but no changeset added:

• posthog-react-native

If this change should ship, run pnpm changeset and select a bump level.
If it isn't user-facing (refactor with no behavior change, internal tooling, generated files), no action needed.

[github-actions]

Coherence

📄 0 spec file errors · ⛔ 0 broken rules · 🚪 2 unchecked inputs · 🐛 0 bugs that came back

What is Coherence?

Coherence compares the code with its spec files (*.spec.md). A spec file lists the rules for one part of the code.

This check read 44 parts of the code and 7 rules.

Note

These findings do not make this check fail.

None of these findings are in files that this pull request changes. You do not need to fix them in this pull request.

🚪 Unchecked inputs (2)

• public api in packages/web/Web.spec.md. The input comes from: host-app.
• webpack plugin in packages/webpack-plugin/Webpack-plugin.spec.md. The input comes from: build.

What this means and how to fix it

Input from outside this code comes in at these places. The spec does not say what checks that input. 10 more places were already like this when Coherence was added. This list does not show them.

To close one of these, find the place by its name in the ## entrances section of its spec file. Add one line under it:

• If all of the input goes through one function that a rule in the spec protects, add guard: <function>.
• If a rule in the spec already checks input from the same source, add the place's name to the entrances: line of that rule.
• If the input needs no check, add control: none - <reason>.

To get the line to add, run npx --no -- coherence scaffold control "<name>".

[github-actions]

SDK performance: posthog-node

Benchmarks completed. No changes flagged for review.

Flags require at least a 5% change in the median and all six pairs agreeing on direction. This is a noise filter, not proof of a performance change or a CI gate.

View all results

Test	Measurement	Before PR	With PR	Change	Assessment
Capture and deliver events (32-byte payload, burst) Shard: capture	Allocations per operation	—	—	—	unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Capture and deliver events (4,096-byte payload, burst) Shard: capture	Allocations per operation	—	—	—	unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Capture and deliver events (32-byte payload, steady) Shard: capture	Allocations per operation	—	—	—	unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Capture and deliver events (4,096-byte payload, steady) Shard: capture	Allocations per operation	—	—	—	unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Queue an event (32-byte payload) Shard: capture	Allocations per operation	—	—	—	unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Queue an event (4,096-byte payload) Shard: capture	Allocations per operation	—	—	—	unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Evaluate all 10 flags Shard: flags-scaling	Allocations per operation	—	—	—	unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Evaluate all 100 flags Shard: flags-scaling	Allocations per operation	—	—	—	unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Evaluate all 1,000 flags Shard: flags-scaling	Allocations per operation	—	—	—	unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Evaluate one boolean flag Shard: flags-single	Allocations per operation	—	—	—	unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Evaluate a cohort-filtered flag Shard: flags-single	Allocations per operation	—	—	—	unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Evaluate a flag (early match) Shard: flags-single	Allocations per operation	—	—	—	unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Evaluate a flag (late match) Shard: flags-single	Allocations per operation	—	—	—	unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Evaluate a flag (no match) Shard: flags-single	Allocations per operation	—	—	—	unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Evaluate a property-filtered flag Shard: flags-single	Allocations per operation	—	—	—	unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Evaluate a regex-filtered flag Shard: flags-single	Allocations per operation	—	—	—	unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Evaluate a rollout flag Shard: flags-single	Allocations per operation	—	—	—	unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Evaluate a multivariate flag Shard: flags-single	Allocations per operation	—	—	—	unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Capture and deliver events (32-byte payload, burst) Shard: capture	Allocated memory per operation (estimated)	10.19 KiB/op	10.41 KiB/op	2.2% more memory	Not flagged
Capture and deliver events (32-byte payload, burst) Shard: capture	Time per operation	16.36 µs/op	17.57 µs/op	7.4% more time	Not flagged
Capture and deliver events (32-byte payload, burst) Shard: capture	Idle process memory (RSS)	102.76 MiB	102.69 MiB	<0.1% less memory	Not flagged
Capture and deliver events (32-byte payload, burst) Shard: capture	Observed peak process memory (RSS)	106.67 MiB	106.23 MiB	0.4% less memory	Not flagged
Capture and deliver events (32-byte payload, burst) Shard: capture	Managed heap after settling	10.05 MiB	10.05 MiB	<0.1% less memory	Not flagged
Capture and deliver events (32-byte payload, burst) Shard: capture	Process memory after settling (RSS)	106.4 MiB	106.01 MiB	0.4% less memory	Not flagged
Capture and deliver events (32-byte payload, burst) Shard: capture	Process CPU time per operation	28.72 µs/op	30.66 µs/op	6.7% more time	Not flagged
Capture and deliver events (32-byte payload, burst) Shard: capture	Lifetime peak process memory (RSS)	106.86 MiB	106.48 MiB	0.4% less memory	Not flagged
Capture and deliver events (4,096-byte payload, burst) Shard: capture	Allocated memory per operation (estimated)	18.4 KiB/op	17.63 KiB/op	4.2% less memory	Not flagged
Capture and deliver events (4,096-byte payload, burst) Shard: capture	Time per operation	30.74 µs/op	30.93 µs/op	0.6% more time	Not flagged
Capture and deliver events (4,096-byte payload, burst) Shard: capture	Idle process memory (RSS)	103.15 MiB	103.11 MiB	<0.1% less memory	Not flagged
Capture and deliver events (4,096-byte payload, burst) Shard: capture	Observed peak process memory (RSS)	113.85 MiB	113.76 MiB	<0.1% less memory	Not flagged
Capture and deliver events (4,096-byte payload, burst) Shard: capture	Managed heap after settling	10.06 MiB	10.05 MiB	<0.1% less memory	Not flagged
Capture and deliver events (4,096-byte payload, burst) Shard: capture	Process memory after settling (RSS)	109.74 MiB	109.69 MiB	<0.1% less memory	Not flagged
Capture and deliver events (4,096-byte payload, burst) Shard: capture	Process CPU time per operation	45.05 µs/op	44.4 µs/op	1.5% less time	Not flagged
Capture and deliver events (4,096-byte payload, burst) Shard: capture	Lifetime peak process memory (RSS)	116.52 MiB	116.48 MiB	<0.1% less memory	Not flagged
Capture and deliver events (32-byte payload, steady) Shard: capture	Allocated memory per operation (estimated)	10.6 KiB/op	10.92 KiB/op	3.1% more memory	Not flagged
Capture and deliver events (32-byte payload, steady) Shard: capture	Time per operation	17.33 µs/op	18.25 µs/op	5.3% more time	Not flagged
Capture and deliver events (32-byte payload, steady) Shard: capture	Idle process memory (RSS)	102.5 MiB	102.6 MiB	<0.1% more memory	Not flagged
Capture and deliver events (32-byte payload, steady) Shard: capture	Observed peak process memory (RSS)	106.54 MiB	106.94 MiB	0.4% more memory	Not flagged
Capture and deliver events (32-byte payload, steady) Shard: capture	Managed heap after settling	10.13 MiB	10.12 MiB	<0.1% less memory	Not flagged
Capture and deliver events (32-byte payload, steady) Shard: capture	Process memory after settling (RSS)	106.54 MiB	106.94 MiB	0.4% more memory	Not flagged
Capture and deliver events (32-byte payload, steady) Shard: capture	Process CPU time per operation	30.48 µs/op	31.72 µs/op	4.1% more time	Not flagged
Capture and deliver events (32-byte payload, steady) Shard: capture	Lifetime peak process memory (RSS)	106.9 MiB	107.09 MiB	0.2% more memory	Not flagged
Capture and deliver events (4,096-byte payload, steady) Shard: capture	Allocated memory per operation (estimated)	18.2 KiB/op	18.01 KiB/op	1.1% less memory	Not flagged
Capture and deliver events (4,096-byte payload, steady) Shard: capture	Time per operation	26.44 µs/op	26.27 µs/op	0.6% less time	Not flagged
Capture and deliver events (4,096-byte payload, steady) Shard: capture	Idle process memory (RSS)	102.89 MiB	102.87 MiB	<0.1% less memory	Not flagged
Capture and deliver events (4,096-byte payload, steady) Shard: capture	Observed peak process memory (RSS)	109.59 MiB	109.61 MiB	<0.1% more memory	Not flagged
Capture and deliver events (4,096-byte payload, steady) Shard: capture	Managed heap after settling	10.13 MiB	10.13 MiB	<0.1% less memory	Not flagged
Capture and deliver events (4,096-byte payload, steady) Shard: capture	Process memory after settling (RSS)	108.45 MiB	108.46 MiB	<0.1% more memory	Not flagged
Capture and deliver events (4,096-byte payload, steady) Shard: capture	Process CPU time per operation	39.6 µs/op	38.94 µs/op	1.7% less time	Not flagged
Capture and deliver events (4,096-byte payload, steady) Shard: capture	Lifetime peak process memory (RSS)	109.62 MiB	109.63 MiB	<0.1% more memory	Not flagged
Queue an event (32-byte payload) Shard: capture	Allocated memory per operation (estimated)	8.66 KiB/op	8.16 KiB/op	5.7% less memory	Not flagged
Queue an event (32-byte payload) Shard: capture	Time per operation	12.43 µs/op	12.21 µs/op	1.8% less time	Not flagged
Queue an event (32-byte payload) Shard: capture	Process CPU time per operation	24.39 µs/op	23.51 µs/op	3.6% less time	Not flagged
Queue an event (4,096-byte payload) Shard: capture	Allocated memory per operation (estimated)	8.87 KiB/op	8.31 KiB/op	6.4% less memory	Not flagged
Queue an event (4,096-byte payload) Shard: capture	Time per operation	11.72 µs/op	12.7 µs/op	8.4% more time	Not flagged
Queue an event (4,096-byte payload) Shard: capture	Process CPU time per operation	22.39 µs/op	24.7 µs/op	10.3% more time	Not flagged
Evaluate all 10 flags Shard: flags-scaling	Allocated memory per operation (estimated)	132.93 KiB/op	133.12 KiB/op	0.1% more memory	Not flagged
Evaluate all 10 flags Shard: flags-scaling	Time per operation	126.02 µs/op	126.63 µs/op	0.5% more time	Not flagged
Evaluate all 10 flags Shard: flags-scaling	Process CPU time per operation	230.13 µs/op	230.05 µs/op	<0.1% less time	Not flagged
Evaluate all 100 flags Shard: flags-scaling	Allocated memory per operation (estimated)	1.22 MiB/op	1.22 MiB/op	0.7% more memory	Not flagged
Evaluate all 100 flags Shard: flags-scaling	Time per operation	1.04 ms/op	1.03 ms/op	0.8% less time	Not flagged
Evaluate all 100 flags Shard: flags-scaling	Process CPU time per operation	1.81 ms/op	1.81 ms/op	<0.1% more time	Not flagged
Evaluate all 1,000 flags Shard: flags-scaling	Allocated memory per operation (estimated)	12.11 MiB/op	12.17 MiB/op	0.5% more memory	Not flagged
Evaluate all 1,000 flags Shard: flags-scaling	Time per operation	10.77 ms/op	10.82 ms/op	0.5% more time	Not flagged
Evaluate all 1,000 flags Shard: flags-scaling	Process CPU time per operation	17.53 ms/op	17.57 ms/op	0.2% more time	Not flagged
Evaluate 1,000 flags under concurrent load Shard: flags-memory	Idle process memory (RSS)	286.02 MiB	286.13 MiB	<0.1% more memory	Not flagged
Evaluate 1,000 flags under concurrent load Shard: flags-memory	Observed peak process memory (RSS)	295.8 MiB	295.68 MiB	<0.1% less memory	Not flagged
Evaluate 1,000 flags under concurrent load Shard: flags-memory	Managed heap after settling	9.69 MiB	9.68 MiB	<0.1% less memory	Not flagged
Evaluate 1,000 flags under concurrent load Shard: flags-memory	Process memory after settling (RSS)	295.73 MiB	295.67 MiB	<0.1% less memory	Not flagged
Evaluate 1,000 flags under concurrent load Shard: flags-memory	Lifetime peak process memory (RSS)	295.8 MiB	296.04 MiB	<0.1% more memory	Not flagged
Refresh 1,000 flag definitions Shard: flags-memory	Idle process memory (RSS)	226.33 MiB	224.69 MiB	0.7% less memory	Not flagged
Refresh 1,000 flag definitions Shard: flags-memory	Observed peak process memory (RSS)	239.48 MiB	238.99 MiB	0.2% less memory	Not flagged
Refresh 1,000 flag definitions Shard: flags-memory	Managed heap after settling	11.7 MiB	11.7 MiB	<0.1% less memory	Not flagged
Refresh 1,000 flag definitions Shard: flags-memory	Process memory after settling (RSS)	234.84 MiB	234.47 MiB	0.2% less memory	Not flagged
Refresh 1,000 flag definitions Shard: flags-memory	Lifetime peak process memory (RSS)	241.09 MiB	240.84 MiB	0.1% less memory	Not flagged
Evaluate one boolean flag Shard: flags-single	Allocated memory per operation (estimated)	17.24 KiB/op	17.12 KiB/op	0.7% less memory	Not flagged
Evaluate one boolean flag Shard: flags-single	Time per operation	50.87 µs/op	51.57 µs/op	1.4% more time	Not flagged
Evaluate one boolean flag Shard: flags-single	Process CPU time per operation	55.86 µs/op	57.08 µs/op	2.2% more time	Not flagged
Evaluate a cohort-filtered flag Shard: flags-single	Allocated memory per operation (estimated)	14.18 KiB/op	14.19 KiB/op	<0.1% more memory	Not flagged
Evaluate a cohort-filtered flag Shard: flags-single	Time per operation	29.25 µs/op	29.78 µs/op	1.8% more time	Not flagged
Evaluate a cohort-filtered flag Shard: flags-single	Process CPU time per operation	35.1 µs/op	36.2 µs/op	3.2% more time	Not flagged
Evaluate a flag (early match) Shard: flags-single	Allocated memory per operation (estimated)	17.66 KiB/op	17.4 KiB/op	1.5% less memory	Not flagged
Evaluate a flag (early match) Shard: flags-single	Time per operation	29.84 µs/op	28.59 µs/op	4.2% less time	Not flagged
Evaluate a flag (early match) Shard: flags-single	Process CPU time per operation	35.44 µs/op	33.76 µs/op	4.7% less time	Not flagged
Evaluate a flag (late match) Shard: flags-single	Allocated memory per operation (estimated)	22.35 KiB/op	22.28 KiB/op	0.3% less memory	Not flagged
Evaluate a flag (late match) Shard: flags-single	Time per operation	29.62 µs/op	30.54 µs/op	3.1% more time	Not flagged
Evaluate a flag (late match) Shard: flags-single	Process CPU time per operation	34.79 µs/op	36.12 µs/op	3.8% more time	Not flagged
Evaluate a flag (no match) Shard: flags-single	Allocated memory per operation (estimated)	16.84 KiB/op	16.91 KiB/op	0.4% more memory	Not flagged
Evaluate a flag (no match) Shard: flags-single	Time per operation	4.24 µs/op	4.14 µs/op	2.4% less time	Not flagged
Evaluate a flag (no match) Shard: flags-single	Process CPU time per operation	7.68 µs/op	7.64 µs/op	0.4% less time	Not flagged
Evaluate a property-filtered flag Shard: flags-single	Allocated memory per operation (estimated)	12.63 KiB/op	12.75 KiB/op	1% more memory	Not flagged
Evaluate a property-filtered flag Shard: flags-single	Time per operation	28.19 µs/op	28.42 µs/op	0.8% more time	Not flagged
Evaluate a property-filtered flag Shard: flags-single	Process CPU time per operation	33.15 µs/op	33.59 µs/op	1.3% more time	Not flagged
Evaluate a regex-filtered flag Shard: flags-single	Allocated memory per operation (estimated)	18.23 KiB/op	18.18 KiB/op	0.3% less memory	Not flagged
Evaluate a regex-filtered flag Shard: flags-single	Time per operation	55.18 µs/op	55.48 µs/op	0.5% more time	Not flagged
Evaluate a regex-filtered flag Shard: flags-single	Process CPU time per operation	60.8 µs/op	61.26 µs/op	0.8% more time	Not flagged
Evaluate a rollout flag Shard: flags-single	Allocated memory per operation (estimated)	14.28 KiB/op	14.34 KiB/op	0.4% more memory	Not flagged
Evaluate a rollout flag Shard: flags-single	Time per operation	39.72 µs/op	40.53 µs/op	2% more time	Not flagged
Evaluate a rollout flag Shard: flags-single	Process CPU time per operation	44.19 µs/op	44.95 µs/op	1.7% more time	Not flagged
Evaluate a multivariate flag Shard: flags-single	Allocated memory per operation (estimated)	17.47 KiB/op	17.55 KiB/op	0.5% more memory	Not flagged
Evaluate a multivariate flag Shard: flags-single	Time per operation	51.86 µs/op	52.75 µs/op	1.7% more time	Not flagged
Evaluate a multivariate flag Shard: flags-single	Process CPU time per operation	57.37 µs/op	59.26 µs/op	3.3% more time	Not flagged

Values are medians of paired measurements. Not flagged does not mean unchanged. Unavailable means a measurement could not be provided, not zero. Estimated allocation measurements retain their instrumentation uncertainty. RSS measures the whole process, not just SDK allocations; observed peaks are sampled checkpoints. Paired ranges in the diagnostics describe variability, not confidence intervals.

Each shard uses its own runner; compare Before PR against With PR within a row, not across shards.

Compared d869c13a0485e174853ad2411966529908cf3c28 → ae16d213d552617069e21d22540b040c54587ec7.

Full report and diagnostics

102 metric rows; 102 rows shown in all results. Omitted or shortened data remain in comparison.json, including per-runner environments, resource limits, measurement methods, samples and checkpoints.