Flutter share_plus Engineering

Treat sharing as a transition across an application trust boundary. After the platform hands content to another application, the Flutter app no longer controls delivery, retention, transformation, or receiver behavior.

Start with evidence

Before changing code:

1. Inspect pubspec.yaml, pubspec.lock, Flutter/Dart constraints, target platforms, and native toolchain requirements.
2. Identify the locked share_plus, cross_file, and relevant export/file package versions.
3. Find every current share invocation, deprecated Share.* call, payload generator, temporary-file owner, Web fallback, result handler, and in-flight guard.
4. Identify the actual payload semantics: text, URI, existing attachment, generated bytes, generated file, hosted URL, or private signed URL.
5. Estimate representative payload sizes and inspect byte, disk, compression, isolate, caching, and cleanup paths.
6. Identify required receiver applications and platform-specific behavior.
7. Separate verified package behavior from receiver-dependent assumptions.

The bundled guide was validated against share_plus 13.3.0 on 2026-08-11. Use the installed package API, README, and changelog as the source of truth when the repository differs, especially for current API shape, iPad behavior, Web fallback, previewThumbnail, filenames, Windows, and toolchain support.

Preserve these invariants

• Use the current SharePlus.instance.share(ShareParams(...)) API.
• Do not assume capability or result parity across Android, Apple, Web, Linux, and Windows.
• Prefer a path-backed XFile when a large file already exists.
• Never call readAsBytes() solely to wrap an existing file in XFile.fromData.
• Use XFile.fromData for genuinely in-memory or generated content, and give it an accurate MIME type and meaningful filename.
• Do not claim path-backed sharing is zero-copy; Android may copy files into its share cache.
• Keep expensive generation, compression, file I/O, and sharing out of build().
• Keep Web sharing directly tied to transient user activation. Prepare expensive Web exports before the final Share click.
• Provide an accurate source-widget sharePositionOrigin on iPad/macOS when positioning is required; do not use an arbitrary giant rectangle.
• Allow only one share invocation per control at a time.
• Treat ShareResult as best-effort interaction feedback, not delivery or business confirmation.
• Treat dismissal as normal user behavior; never auto-retry it.
• Treat subject, title, MIME hints, filenames, and multi-attachment support as receiver-dependent.
• Never share access tokens, refresh tokens, credentials, private keys, or unreviewed sensitive content.
• Treat private and signed URLs as bearer-like information once shared.
• Own and clean only application-created temporary exports; never delete the entire shared temporary directory.
• Surface Web download/email fallback as fallback behavior, not native-share success.
• Do not add obsolete Android storage permissions or manual FileProvider setup solely for current share_plus.
• Test real devices and important receiver applications; emulator-only success is insufficient.

Choose the smallest correct payload

Use this decision order:

1. Share a URI when the hosted experience is the product and the recipient can access it.
2. Share an existing path-backed file when the recipient needs a standalone attachment.
3. Use XFile.fromData for small content that genuinely exists only in memory.
4. Materialize large generated content once to an owned file, then share the path-backed file.
5. Use a short-lived signed URL only after reviewing access lifetime and forwarding risk.
6. Choose and label Web fallback explicitly when native Web Share is unavailable.

Prefer the first option that preserves product semantics, privacy, platform support, and acceptable memory/disk cost.

Route to the production guide

Read only the relevant sections of references/production-guide.md. Locate sections before reading them with:

rg -n '^#{1,3} (SECTION|RELATED SECTION)$' references/production-guide.md

Use these search headings:

For a full cross-platform sharing or production-readiness audit, read the entire guide after completing the repository inventory.

Implement at the payload lifecycle boundary

• Reuse an existing share helper or export path when it already owns real cross-cutting concerns.
• Add a share service only when it centralizes actual export caching, privacy, fallback, duplicate prevention, analytics, or testability needs.
• Fix large-file memory spikes at payload generation/materialization rather than micro-optimizing the small plugin invocation.
• Derive the popover origin from the live initiating widget after asynchronous work, with lifecycle checks.
• Keep UI state changes lifecycle-safe and release the in-flight guard in all result and error paths.
• Do not build receiver-specific guarantees on generic share-sheet behavior.

Validate the result

Run the narrowest relevant Dart/Flutter checks, then test release-like builds on the affected platforms and representative receivers. Cover changed paths from this matrix:

• text, URI, single-file, multi-file, and generated-content payloads;
• empty/missing files, wrong MIME, receiver rejection, dismissal, and unavailable capability;
• iPad/macOS positioning from the actual initiating widget;
• Web native share under user activation plus each configured fallback;
• representative small and large payload memory/disk behavior;
• one in-flight share action under rapid taps;
• temporary export cleanup without deleting unrelated files;
• privacy review for content, metadata, filenames, and URLs;
• release builds on each supported target and important receiver application.

Never claim a share was delivered from ShareResultStatus.success. Report any platform, receiver, fallback, or payload-size path that was not executed.