Skip to content

docs(mobile/4): document env-gated plugin feature bundles - #463

Open
shanerbaner82 wants to merge 1 commit into
mainfrom
docs/plugin-feature-gates
Open

docs(mobile/4): document env-gated plugin feature bundles#463
shanerbaner82 wants to merge 1 commit into
mainfrom
docs/plugin-feature-gates

Conversation

@shanerbaner82

Copy link
Copy Markdown
Contributor

What

Documents the features key in nativephp.json, which lets a plugin declare optional pieces of itself behind an environment variable so apps compile in only what they enable.

New page: Plugins → Feature Bundles (order 725, between Permissions & Dependencies and Advanced Configuration), plus a short cross-reference from permissions-dependencies.md so someone declaring a heavy SDK finds it.

Why

A plugin wrapping a large SDK forces every app to pay for every capability. nativephp/mobile-firebase is the motivating case: push, Crashlytics, App Check, Performance, and In-App Messaging all in one plugin — an app that only wants push shouldn't link the crash reporter and attestation provider.

What the page covers

  • The problem, then the manifest shape (using the real Crashlytics bundle as the example)
  • A table of what a bundle may declare, and the merge semantics — lists concatenate, maps merge key-wise, dependencies recurses
  • Why feature sources live in resources/features/<feature>/<platform>/ rather than a subdirectory of resources/ios: those roots are copied recursively, so a gated-off subdirectory would still compile in and reference SDK products that were never linked. This is the constraint a plugin author is most likely to get wrong first.
  • Sharing one SDK package across features — declare the same url with only the products you need; the compiler attaches them to the existing package reference
  • Truthiness rules, and an explicit "what a disabled feature costs: nothing" list
  • A callout on the version requirement: on an older core the key is silently ignored, so pin the constraint and add a PluginManifest test that fails loudly
  • A nudge to document each variable in the plugin README, since app developers can't discover features by reading code

⚠️ Do not merge before the core PR

This documents behavior from NativePHP/mobile-air#289, which is still open. Merging ahead of it would publish docs for a feature nobody has.

🤖 Generated with Claude Code

A plugin wrapping a large SDK can now declare optional pieces of itself
behind an environment variable, so apps compile in only what they ask
for. Covers the manifest shape, merge semantics, why feature sources
live outside resources/ios|android, sharing one SDK package across
features, and the version caveat that an older core ignores the key
silently.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant