@molecule/app-splash-screen

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.

Splash screen control interface for molecule.dev.

Framework-agnostic core for the native launch/splash screen through a swappable SplashScreenProvider: show/hide with optional fade, state queries (getState, isVisible), configure, and readiness helpers (hideWhenReady, showForMinDuration, createSplashController).

Quick Start

import { hasProvider, hide } from '@molecule/app-splash-screen'

async function bootApp(loadInitialData: () => Promise<void>): Promise<void> {
  await loadInitialData()
  // Hide ONLY after the first real frame is renderable — and ALWAYS hide,
  // even on error, or the app hangs on the splash forever.
  if (hasProvider()) {
    await hide({ fadeOutDuration: 200 }).catch(() => hide())
  }
}

Type

native

Installation

npm install @molecule/app-splash-screen @molecule/app-bond @molecule/app-i18n @molecule/app-logger

API

Interfaces

SplashScreenCapabilities

Splash screen capabilities

interface SplashScreenCapabilities {
  /** Whether splash screen control is supported */
  supported: boolean
  /** Whether spinner is supported */
  spinnerSupported: boolean
  /** Whether configuration is supported */
  configurable: boolean
  /** Whether background color can be changed */
  dynamicBackground: boolean
}

SplashScreenConfig

Splash screen configuration

interface SplashScreenConfig {
  /** Background color */
  backgroundColor?: string
  /** Show spinner */
  showSpinner?: boolean
  /** Spinner color */
  spinnerColor?: string
  /** Android spinner style */
  androidSpinnerStyle?: 'horizontal' | 'small' | 'large'
  /** iOS spinner style */
  iosSpinnerStyle?: 'small' | 'large'
  /** Whether to auto-hide on app ready */
  autoHide?: boolean
  /** Duration in milliseconds before auto-hide */
  showDuration?: number
  /** Fade in duration in milliseconds */
  fadeInDuration?: number
  /** Fade out duration in milliseconds */
  fadeOutDuration?: number
  /** Scale mode for splash image */
  scaleMode?: 'fill' | 'aspectFill' | 'aspectFit' | 'center'
  /** Launch show duration (iOS) */
  launchShowDuration?: number
  /** Launch auto hide (iOS) */
  launchAutoHide?: boolean
}

SplashScreenHideOptions

Splash screen hide options

interface SplashScreenHideOptions {
  /** Fade out duration in milliseconds */
  fadeOutDuration?: number
}

SplashScreenProvider

Splash screen provider interface

interface SplashScreenProvider {
  /**
   * Show the splash screen
   * @param options - Show options
   */
  show(options?: SplashScreenShowOptions): Promise<void>

  /**
   * Hide the splash screen
   * @param options - Hide options
   */
  hide(options?: SplashScreenHideOptions): Promise<void>

  /**
   * Get current splash screen state
   */
  getState(): Promise<SplashScreenState>

  /**
   * Check if splash screen is visible
   */
  isVisible(): Promise<boolean>

  /**
   * Configure splash screen settings
   * @param config - Configuration options
   */
  configure?(config: SplashScreenConfig): Promise<void>

  /**
   * Get the platform's splash screen capabilities.
   * @returns The capabilities indicating splash screen control, spinner, and configuration support.
   */
  getCapabilities(): Promise<SplashScreenCapabilities>
}

SplashScreenShowOptions

Splash screen show options

interface SplashScreenShowOptions {
  /** Whether to auto-hide after showDuration */
  autoHide?: boolean
  /** Duration in milliseconds before auto-hide */
  showDuration?: number
  /** Fade in duration in milliseconds */
  fadeInDuration?: number
  /** Fade out duration in milliseconds */
  fadeOutDuration?: number
}

SplashScreenState

Splash screen state

interface SplashScreenState {
  /** Whether splash screen is currently visible */
  visible: boolean
  /** Whether currently animating */
  animating: boolean
}

Functions

configure(config)

Configure splash screen appearance settings. Logs a warning if the provider does not support configuration.

function configure(config: SplashScreenConfig): Promise<void>

• config — Configuration including background color, spinner, and animation settings.

Returns: A promise that resolves when the configuration is applied.

createSplashController()

Create a task-based splash screen controller for complex multi-step loading scenarios. Register tasks with startTask(), complete them with completeTask(). The splash screen is automatically hidden when all registered tasks are complete.

function createSplashController(): {
  startTask(taskId: string): void
  completeTask(taskId: string, options?: SplashScreenHideOptions): Promise<void>
  forceHide(options?: SplashScreenHideOptions): Promise<void>
  getPendingCount(): number
  isComplete(): boolean
  reset(): void
}

Returns: A controller object with methods to manage loading tasks.

getCapabilities()

Get the platform's splash screen capabilities.

function getCapabilities(): Promise<SplashScreenCapabilities>

Returns: The capabilities indicating splash screen control, spinner, and configuration support.

getProvider()

Get the current splash screen provider.

function getProvider(): SplashScreenProvider

Returns: The active SplashScreenProvider instance.

getState()

Get the current splash screen state.

function getState(): Promise<SplashScreenState>

Returns: The state including visibility and animation status.

hasProvider()

Check if a splash screen provider has been registered.

function hasProvider(): boolean

Returns: Whether a SplashScreenProvider has been bonded.

hide(options)

Hide the splash screen with optional fade-out animation.

function hide(options?: SplashScreenHideOptions): Promise<void>

• options — Hide options including fade-out duration.

Returns: A promise that resolves when the splash screen is hidden.

hideWhenReady(condition, options)

Hide the splash screen once a readiness condition is met. Evaluates the condition immediately; hides only if it returns true.

function hideWhenReady(
  condition: () => Promise<boolean> | boolean,
  options?: SplashScreenHideOptions,
): Promise<void>

• condition — Function returning whether the app is ready (sync or async).
• options — Fade-out animation options for hiding.

isVisible()

Check if the splash screen is currently visible.

function isVisible(): Promise<boolean>

Returns: Whether the splash screen is showing.

setProvider(provider)

Set the splash screen provider.

function setProvider(provider: SplashScreenProvider): void

• provider — SplashScreenProvider implementation to register.

show(options)

Show the splash screen with optional animation and auto-hide configuration.

function show(options?: SplashScreenShowOptions): Promise<void>

• options — Show options including auto-hide, duration, and fade settings.

Returns: A promise that resolves when the splash screen is shown.

showForMinDuration(minDuration, task, options)

Run an async task while ensuring the splash screen stays visible for at least minDuration milliseconds. Hides the splash after both the task completes and the minimum duration elapses.

function showForMinDuration(
  minDuration: number,
  task: () => Promise<T>,
  options?: SplashScreenHideOptions,
): Promise<T>

• minDuration — Minimum time in milliseconds to keep the splash screen visible.
• task — The async initialization task to run while splash is shown.
• options — Fade-out animation options for hiding.

Returns: The return value of the task.

Injection Notes

Requirements

Peer dependencies:

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

Runtime Dependencies

• @molecule/app-bond

• @molecule/app-i18n

• @molecule/app-logger

• Every accessor THROWS until setProvider() is called. The one prebuilt bond is @molecule/app-splash-screen-react-native; web has no bond and no OS splash (an HTML/CSS boot screen is app code, not this package) — on web, skip wiring and gate on hasProvider().

• The #1 failure mode is never calling hide(): with the react-native bond, creating the provider arms prevent-auto-hide, so an app that forgets hide() (or throws before it) sits on the splash forever. Put hide() in a finally.

• Runtime show()/hide() OPTIONS (fade, duration, spinner) are best-effort: the react-native bond ignores them (getCapabilities() reports spinnerSupported/configurable: false; splash artwork is build-time config there). Check capabilities instead of assuming.

• show() mid-session cannot be relied on to re-display a hidden native splash — treat the splash as a launch-only surface and use an in-app loader for later blocking work.

Translations

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