@molecule/app-share

Native share-sheet interface for molecule.dev.

Framework-agnostic core for handing content to the platform share sheet through a swappable ShareProvider: share (title/text/url), shareText, shareUrl, shareFiles, feature detection (canShare, canShareContent, getCapabilities) — plus provider-free socialUrls builders (web intent links for X/Facebook/LinkedIn/WhatsApp/etc.) that work in ANY browser as a fallback.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import { canShare, hasProvider, shareUrl, socialUrls } from '@molecule/app-share'

async function shareArticle(url: string, title: string): Promise<void> {
  if (hasProvider() && (await canShare())) {
    const result = await shareUrl(url, title)
    if (result.completed) return
  }
  // Fallback that needs no provider: open a share-intent URL
  window.open(socialUrls.twitter(title, url), '_blank')
}

Type

native

Installation

npm install @molecule/app-share @molecule/app-bond @molecule/app-i18n

API

Interfaces

ShareContent

Share content options

interface ShareContent {
  /** Title of the shared content */
  title?: string
  /** Text content to share */
  text?: string
  /** URL to share */
  url?: string
  /** Dialog title (Android only) */
  dialogTitle?: string
}

ShareFile

A file attachment for sharing, with path/URI, MIME type, and display name.

interface ShareFile {
  /** File path or URI */
  path: string
  /** MIME type of the file */
  mimeType?: string
  /** Display name for the file */
  name?: string
}

ShareOptions

Share options including files

interface ShareOptions extends ShareContent {
  /** Files to share */
  files?: ShareFile[]
}

ShareResult

Result of a share operation: completion status, chosen activity/app, and any error.

interface ShareResult {
  /** Whether sharing was completed successfully */
  completed: boolean
  /** Activity type that was used (iOS) or package name (Android) */
  activityType?: string
  /** Error message if sharing failed */
  error?: string
}

ShareCapabilities

Share capabilities

interface ShareCapabilities {
  /** Whether sharing is supported */
  supported: boolean
  /** Whether file sharing is supported */
  fileSharing: boolean
  /** Whether multiple files can be shared */
  multipleFiles: boolean
  /** Supported MIME types (if available) */
  supportedMimeTypes?: string[]
}

ShareProvider

Share provider interface

interface ShareProvider {
  /**
   * Share content using the native share sheet.
   * @param options - Content, files, and dialog configuration to share.
   * @returns The share result indicating completion status and activity type.
   */
  share(options: ShareOptions): Promise<ShareResult>

  /**
   * Share text content via the native share sheet.
   * @param text - The text content to share.
   * @param title - Optional title for the share dialog.
   * @returns The share result indicating completion status and activity type.
   */
  shareText(text: string, title?: string): Promise<ShareResult>

  /**
   * Share a URL via the native share sheet.
   * @param url - The URL to share.
   * @param title - Optional title for the share dialog.
   * @returns The share result indicating completion status and activity type.
   */
  shareUrl(url: string, title?: string): Promise<ShareResult>

  /**
   * Share one or more files via the native share sheet.
   * @param files - The files to share, with paths and optional MIME types.
   * @param options - Additional share content (title, text, URL) to include.
   * @returns The share result indicating completion status and activity type.
   */
  shareFiles(files: ShareFile[], options?: ShareContent): Promise<ShareResult>

  /**
   * Check if the native share sheet is available on this platform.
   * @returns Whether sharing is supported.
   */
  canShare(): Promise<boolean>

  /**
   * Check if the given content (text, URL, files) can be shared on this platform.
   * @param options - The share options to validate.
   * @returns Whether the specified content can be shared.
   */
  canShareContent(options: ShareOptions): Promise<boolean>

  /**
   * Get the platform's sharing capabilities.
   * @returns The capabilities indicating file sharing support and allowed MIME types.
   */
  getCapabilities(): Promise<ShareCapabilities>
}

Functions

setProvider(provider)

Set the share provider.

function setProvider(provider: ShareProvider): void

• provider — ShareProvider implementation to register.

getProvider()

Get the current share provider.

function getProvider(): ShareProvider

Returns: The active ShareProvider instance.

hasProvider()

Check if a share provider has been registered.

function hasProvider(): boolean

Returns: Whether a ShareProvider has been bonded.

share(options)

Share content using the native share sheet.

function share(options: ShareOptions): Promise<ShareResult>

• options — Content, files, and dialog configuration to share.

Returns: The share result indicating completion status and activity type.

shareText(text, title)

Share text content via the native share sheet.

function shareText(text: string, title?: string): Promise<ShareResult>

• text — The text content to share.
• title — Optional title for the share dialog.

Returns: The share result indicating completion status and activity type.

shareUrl(url, title)

Share a URL via the native share sheet.

function shareUrl(url: string, title?: string): Promise<ShareResult>

• url — The URL to share.
• title — Optional title for the share dialog.

Returns: The share result indicating completion status and activity type.

shareFiles(files, options)

Share one or more files via the native share sheet.

function shareFiles(files: ShareFile[], options?: ShareContent): Promise<ShareResult>

• files — The files to share, with paths and optional MIME types.
• options — Additional share content (title, text, URL) to include.

Returns: The share result indicating completion status and activity type.

canShare()

Check if the native share sheet is available on this platform. Returns false without throwing if no provider is set.

function canShare(): Promise<boolean>

Returns: Whether sharing is supported.

canShareContent(options)

Check if the given content can be shared on this platform. Returns false without throwing if no provider is set.

function canShareContent(options: ShareOptions): Promise<boolean>

• options — The share options to validate.

Returns: Whether the specified content can be shared.

getCapabilities()

Get the platform's sharing capabilities.

function getCapabilities(): Promise<ShareCapabilities>

Returns: The capabilities indicating file sharing support and allowed MIME types.

getMimeType(filename)

Infer a MIME type from a file extension. Supports common image, document, text, media, and archive formats. Falls back to 'application/octet-stream'.

function getMimeType(filename: string): string

• filename — The filename or path to extract the extension from.

Returns: The inferred MIME type string.

Constants

socialUrls

Pre-built social media share URL generators. Each method returns a URL that opens the platform's share dialog with the provided content pre-filled.

const socialUrls: {
  readonly twitter: (text: string, url?: string) => string
  readonly facebook: (url: string) => string
  readonly linkedin: (url: string) => string
  readonly whatsapp: (text: string) => string
  readonly telegram: (url: string, text?: string) => string
  readonly email: (subject: string, body: string) => string
}

Injection Notes

Requirements

Peer dependencies:

• @molecule/app-bond ^1.0.1
• @molecule/app-i18n ^1.0.1

Runtime Dependencies

• @molecule/app-bond

• @molecule/app-i18n

• Every share call THROWS until setProvider() is called — no prebuilt provider package ships with molecule. On web, wire a thin ShareProvider over navigator.share/navigator.canShare; on native, implement against your container's share module. Gate UI on hasProvider() + canShare() and keep the socialUrls fallback for everything else.

• The Web Share API needs HTTPS AND a user gesture (call share directly in the click handler — an await before it can void the gesture in Safari), and is missing from most DESKTOP browsers (Firefox/Chrome- Linux) — desktop fallback is not optional.

• shareFiles support is much narrower than text/url support — check canShareContent({ files }) (per-content probe) before offering it.

• A dismissed sheet is NOT an error: expect result.completed === false with no error and stay quiet about it.

Translations

Translation strings are provided by @molecule/app-locales-share.