@nebula-rn/sdk

@nebula-rn/sdk is Nebula's core runtime package, providing both host initialization API (NebulaAPI) and miniapp client API (MiniAppAPI, which is an alias export of NebulaAPI).

Version: 0.1.0

Peer Dependencies: react >= 19, react-native >= 0.83

Host Initialization

NebulaAPI.wrap(options)

A higher-order component (HOC) that wraps the host app's root component and initializes the Nebula runtime. Automatically calls startApiServer() when the component mounts, and also calls setServerBaseURL() if serverBaseURL is non-empty.

function wrap(
  options: NebulaHostOptions,
): <P>(Component: React.ComponentType<P>) => React.ComponentType<P>;

Parameters NebulaHostOptions:

Example:

import { NebulaAPI } from '@nebula-rn/sdk';
import { defaultHostApis } from '@nebula-rn/host-apis';

export default NebulaAPI.wrap({
  serverBaseURL: 'https://api.example.com',
  hostApis: defaultHostApis,
})(App);

NebulaAPI.startApiServer()

Starts the host-side API message processing service, listening for protocol requests from miniapps. Typically called automatically by wrap(); calling it manually is idempotent.

function startApiServer(): void;

Request types handled:

Internal error codes:

NebulaAPI.stopApiServer()

Stops the host-side API message listener and cancels bridge event subscriptions.

function stopApiServer(): void;

NebulaAPI.setServerBaseURL(serverBaseURL)

Sets the base URL for the host service, persisting it to native storage. This URL is used to resolve relative paths when installing and updating miniapps.

function setServerBaseURL(
  serverBaseURL?: string | null,
): Promise<ServerBaseURLResult>;

Parameters:

Return value ServerBaseURLResult:

Error codes:

NebulaAPI.getServerBaseURL()

Gets the currently configured service base URL.

function getServerBaseURL(): Promise<ServerBaseURLResult>;

Return value ServerBaseURLResult:

Miniapp Installation

NebulaAPI.installMiniApp(appId, bundleURL)

Downloads and installs a miniapp bundle from a remote URL (production mode). Automatically fetches and stores the app.json manifest.

function installMiniApp(
  appId: string,
  bundleURL: string,
): Promise<MiniAppResult>;

Parameters:

Return value MiniAppResult:

Platform differences:

Error codes:

NebulaAPI.installMiniAppWithBundleURL(appId, bundleURL, connectToURLMetroServer?)

Installs a miniapp with the specified bundle URL, using connectToURLMetroServer to determine whether to treat it as a Metro development runtime connected to that URL.

function installMiniAppWithBundleURL(
  appId: string,
  bundleURL: string,
  connectToURLMetroServer?: boolean,
): Promise<MiniAppResult>;

Parameters:

Return value MiniAppResult:

Behavior differences:

Error codes:

Opening and Preloading Miniapps

NebulaAPI.openMiniApp(appId, initialProps?, versionType?)

Opens an installed miniapp and displays it to the user. If not installed locally, it will automatically install the specified version type (defaults to release). If the miniapp is in production mode and updateStrategy is 'auto', it will automatically check for and apply updates before opening (update failure does not block opening).

function openMiniApp(
  appId: string,
  initialProps?: Record<string, unknown>,
  versionType?: 'release' | 'experience',
): Promise<MiniAppResult>;

Parameters:

Return value MiniAppResult:

Platform differences:

Error codes:

NebulaAPI.openMiniAppWithBundleURL(appId, bundleURL, initialProps?, connectToURLMetroServer?)

Installs and immediately opens a miniapp. Equivalent to calling installMiniAppWithBundleURL() followed by openMiniApp().

function openMiniAppWithBundleURL(
  appId: string,
  bundleURL: string,
  initialProps?: Record<string, unknown>,
  connectToURLMetroServer?: boolean,
): Promise<MiniAppResult>;

Parameters:

NebulaAPI.preloadMiniApp(appId)

Preloads an installed miniapp in the background, creating the runtime and root view in advance to reduce subsequent open time.

function preloadMiniApp(appId: string): Promise<MiniAppResult>;

Parameters:

Return value MiniAppResult:

Platform implementation differences:

Error codes:

NebulaAPI.preloadMiniAppWithBundleURL(appId, bundleURL, connectToURLMetroServer?)

Installs then preloads a miniapp. Equivalent to calling installMiniAppWithBundleURL() followed by preloadMiniApp().

function preloadMiniAppWithBundleURL(
  appId: string,
  bundleURL: string,
  connectToURLMetroServer?: boolean,
): Promise<MiniAppResult>;

Parameters:

Error codes:

Version and Update

NebulaAPI.checkMiniAppUpdate(appId)

Checks whether an update is available for a miniapp. Fetches the remote app.json manifest and compares version numbers using semver numeric segment comparison.

function checkMiniAppUpdate(appId: string): Promise<MiniAppUpdateInfo>;

Parameters:

Return value MiniAppUpdateInfo:

Cases where hasUpdate: false is returned:

• Miniapp is not installed
• In development mode
• No sourceUrl (non-remote app)
• Unable to derive manifest URL

Version comparison logic: Split by . into numeric segments and compare segment by segment; missing segments default to 0.

NebulaAPI.applyMiniAppUpdate(appId)

Checks for and applies a miniapp update. Internally calls checkMiniAppUpdate() first; if an update is available, calls installMiniAppWithBundleURL() to download and install.

function applyMiniAppUpdate(appId: string): Promise<MiniAppUpdateInfo>;

Parameters:

Return value: Same as MiniAppUpdateInfo.

Miniapp Information

NebulaAPI.getInstalledMiniAppInfo(appId)

Gets local installation information for a miniapp.

function getInstalledMiniAppInfo(
  appId: string,
): Promise<InstalledMiniAppInfoResult>;

Parameters:

Return value InstalledMiniAppInfoResult:

InstalledMiniAppInfo fields:

NebulaAPI.getInstalledMiniApps()

Gets the list of IDs of all installed miniapps.

function getInstalledMiniApps(): Promise<InstalledMiniAppsResult>;

Return value InstalledMiniAppsResult:

Navigation

MiniAppAPI.navigateTo(url)

Navigates to a new page, pushing the current page onto the page stack.

function navigateTo(url: string): Promise<NavigationResult>;

Parameters:

Return value NavigationResult:

Platform differences:

MiniAppAPI.redirectTo(url)

Navigates to a new page, replacing the current page (cannot go back).

function redirectTo(url: string): Promise<NavigationResult>;

Parameters:

MiniAppAPI.reLaunch(url)

Clears all page stacks and opens the target page.

function reLaunch(url: string): Promise<NavigationResult>;

Parameters:

MiniAppAPI.navigateBack(delta?)

Pops pages from the page stack.

function navigateBack(delta?: number): Promise<NavigationResult>;

Parameters:

Page Styling

MiniAppAPI.setPageStyle(style)

Sets the appearance style of the current page.

function setPageStyle(style: NebulaPageStyle): Promise<NavigationResult>;

Parameters NebulaPageStyle:

MiniAppAPI.setNavigationBarTitle(title)

Convenience method for setting the navigation bar title. Internally calls setPageStyle({ navigationBarTitleText: title }).

function setNavigationBarTitle(title: string): Promise<NavigationResult>;

MiniAppAPI.setNavigationBarColor(options)

Convenience method for setting the navigation bar color.

function setNavigationBarColor(options: {
  backgroundColor?: string;
  frontColor?: string;
}): Promise<NavigationResult>;

Parameters:

Device and App

MiniAppAPI.getAppId()

Gets the current miniapp ID. Synchronous method.

function getAppId(): string | null;

Return value: Current miniapp ID, or null if not initialized.

MiniAppAPI.getSandboxPath()

Gets the miniapp's file sandbox path.

function getSandboxPath(): string;

Return value: Sandbox path string, e.g., /Documents/MiniApps/{appId}.

MiniAppAPI.getDeviceInfo()

Gets device information. Synchronous blocking call.

function getDeviceInfo(): DeviceInfo;

Return value DeviceInfo:

Platform differences:

MiniAppAPI.showToast(title)

Displays a brief toast message.

function showToast(title: string): Promise<NavigationResult>;

Parameters:

Platform differences:

Host Communication

MiniAppAPI.invokeHostApi(apiName, payload?, version?, timeoutMs?)

Calls a host-registered API from a miniapp. Sends a request through the Nebula protocol layer (api.v1) and waits for a response.

function invokeHostApi<TData = unknown>(
  apiName: string,
  payload?: Record<string, unknown>,
  version?: string,
  timeoutMs?: number,
): Promise<NebulaApiInvokeResult<TData>>;

Parameters:

Return value NebulaApiInvokeResult<TData>:

// Success
{ ok: true, data: TData }

// Failure
{ ok: false, error: { code: string, message: string, details?: Record<string, unknown> } }

Error codes:

Timeout: 15000ms. After timeout, the request is cleaned up and the Promise rejects with "Timed out waiting for host API: {apiName}".

MiniAppAPI.postMessageToHost(message)

Sends a message to the host.

function postMessageToHost(
  message: Record<string, unknown>,
): Promise<NavigationResult>;

Parameters:

MiniAppAPI.onHostMessage(listener)

Subscribes to messages from the host.

function onHostMessage(listener: (event: BridgeMessage) => void): () => void;

BridgeMessage fields:

Return value: Unsubscribe function.

NebulaAPI.postMessageToMiniApp(appId, message)

Sends a message from the host to a specified miniapp.

function postMessageToMiniApp(
  appId: string,
  message: Record<string, unknown>,
): Promise<NavigationResult>;

Parameters:

NebulaAPI.addMiniAppMessageListener(listener)

Subscribes to messages from miniapps (for host-side use).

function addMiniAppMessageListener(
  listener: (event: BridgeMessage) => void,
): () => void;

Return value: Unsubscribe function.

Capability Detection

MiniAppAPI.getCapabilities()

Gets the list of all API capabilities registered by the host.

function getCapabilities(): Promise<{
  bridgeVersion: string;
  capabilities: NebulaHostCapabilityMap;
}>;

Return value:

NebulaHostCapabilityDescriptor fields:

Timeout: 15000ms (fixed).

MiniAppAPI.isSupported(apiName, minimumVersion?)

Checks whether a specified API is supported by the host, optionally validating a minimum version.

function isSupported(
  apiName: string,
  minimumVersion?: string,
): Promise<boolean>;

Parameters:

Return value: true if supported and meets version requirements.

MiniAppAPI.getHostApiDescriptions(timeoutMs?)

Gets detailed documentation descriptions of host-registered APIs.

function getHostApiDescriptions(
  timeoutMs?: number,
): Promise<NebulaHostApiDescriptionMap>;

Parameters:

Return value NebulaHostApiDescriptionMap:

Record<string, NebulaHostApiDescription>;

NebulaHostApiDescription fields:

Host Visibility and Modal

MiniAppAPI.bringHostToFront()

Brings the host app to the foreground while hiding the miniapp (preserves state for restoration).

function bringHostToFront(): Promise<HostVisibilityResult>;

Return value HostVisibilityResult:

MiniAppAPI.restoreMiniApp(token?)

Restores a miniapp previously hidden via bringHostToFront().

function restoreMiniApp(token?: string | null): Promise<HostVisibilityResult>;

Parameters:

MiniAppAPI.presentHostModal(moduleName, props?)

Presents a host-side React Native module as a Modal.

function presentHostModal(
  moduleName: string,
  props?: Record<string, unknown>,
): Promise<NavigationResult>;

Parameters:

Platform differences:

Error codes:

MiniAppAPI.dismissHostModal()

Dismisses the currently presented host Modal.

function dismissHostModal(): Promise<NavigationResult>;

Page Lifecycle

MiniAppAPI.onPageLifecycle(listener)

Subscribes to page lifecycle events.

function onPageLifecycle(
  listener: (event: PageLifecycleEvent) => void,
): () => void;

PageLifecycleEvent fields:

Return value: Unsubscribe function.

Lifecycle Hooks

usePageOnLoad(callback)

Executes when the page loads for the first time, receiving route parameters. Triggers once when the component mounts.

function usePageOnLoad(
  callback: (params: Record<string, unknown>) => void,
): void;

Parameters:

usePageOnShow(callback)

Executes every time the page becomes visible. Triggers when the component mounts, then on every 'show' lifecycle event.

function usePageOnShow(callback: () => void): void;

usePageOnReady(callback)

Executes after the page has rendered (after the first animation frame). Uses requestAnimationFrame() internally.

function usePageOnReady(callback: () => void): void;

usePageOnHide(callback)

Executes when the page becomes invisible. Triggers on the 'hide' lifecycle event.

function usePageOnHide(callback: () => void): void;

usePageOnUnload(callback)

Executes when the page is unloaded. Triggers when the component unmounts (cleanup function).

function usePageOnUnload(callback: () => void): void;

Route Registration

NebulaAPI.registerRoutes(appId, routes)

Registers the miniapp's route table, typically called when the miniapp starts.

function registerRoutes(
  appId: string,
  routes: Record<string, string>,
): Promise<void>;

Parameters:

NebulaAPI.registerManifest(appId, manifest)

Registers the complete miniapp manifest (extended route table with page configurations).

function registerManifest(
  appId: string,
  manifest: RegisteredMiniAppManifest,
): Promise<void>;

Parameters RegisteredMiniAppManifest:

Error codes:

Host API Registration

NebulaAPI.registerApiHandler(apiName, handler)

Manually registers a host API handler. Automatically calls startApiServer() if the API Server has not been started.

function registerApiHandler(
  apiName: string,
  handler: NebulaHostApiHandler,
): void;

Parameters NebulaHostApiHandler:

NebulaAPI.unregisterApiHandler(apiName)

Unregisters a host API handler.

function unregisterApiHandler(apiName: string): void;

NebulaAPI.getRegisteredCapabilities()

Gets the version and support status of all registered APIs (asynchronously resolves supported functions).

function getRegisteredCapabilities(): Promise<NebulaHostCapabilityMap>;

NebulaAPI.getRegisteredApiDescriptions()

Synchronously gets the documentation descriptions of all registered APIs.

function getRegisteredApiDescriptions(): NebulaHostApiDescriptionMap;

Host Feature Factories

createHostApiFeature(options)

Creates a UI-less host API feature for registration with hostApis in NebulaAPI.wrap().

function createHostApiFeature(
  options: RegisterHostApiOptions,
): NebulaHostFeature;

Parameters RegisterHostApiOptions:

Return value NebulaHostFeature: A feature object containing name, description, and a register() method.

createHostModalApiFeature(options)

Creates a host API feature that requires Modal UI. Automatically presents a Modal when called, and returns the result when the Modal closes.

function createHostModalApiFeature<TPayload, TRequest>(
  options: RegisterHostModalApiOptions<TPayload, TRequest>,
): NebulaHostFeature;

Parameters RegisterHostModalApiOptions:

createHostModalChannel()

Creates a bidirectional request-response channel for Modals, used for communication between host components and API calls.

function createHostModalChannel<
  TRequest extends object,
>(): HostModalChannel<TRequest>;

Return value HostModalChannel<TRequest>:

Helper Functions

createHostApiSuccess(data)

Creates a successful API return result.

function createHostApiSuccess<TData>(data: TData): NebulaApiInvokeResult<TData>;
// Returns { ok: true, data }

createHostApiFailure(code, message)

Creates a failed API return result.

function createHostApiFailure(
  code: string,
  message: string,
): NebulaApiInvokeResult;
// Returns { ok: false, error: { code, message } }

definePageConfig(config)

TypeScript helper function for page configuration (pass-through, provides type constraints only).

function definePageConfig<T extends MiniAppPageConfig>(config: T): T;

Parameters MiniAppPageConfig:

createMiniAppPage(Component)

Higher-order component that wraps a miniapp page component, providing Nebula context. Automatically calls MiniAppAPI.bootstrap() and provides MiniAppPageContext.

function createMiniAppPage<P extends Record<string, unknown>>(
  Component: React.ComponentType<P>,
): React.ComponentType<P>;

Reserved Props (not passed to child component): appId, instanceId, sandboxPath, title, __pageConfig, __routePath, __routeUrl.

Type Definitions

type MiniAppUpdateStrategy = 'auto' | 'manual';

type MiniAppResult = {
  success: boolean;
  appId: string;
  mode?: string;
};

type MiniAppUpdateInfo = {
  appId: string;
  currentVersion?: string | null;
  latestVersion?: string | null;
  hasUpdate: boolean;
  updateStrategy: 'auto' | 'manual';
  mode?: string | null;
  sourceUrl?: string | null;
};

type NebulaApiInvokeResult<T = unknown> =
  | { ok: true; data: T }
  | { ok: false; error: NebulaApiError };

type NebulaApiError = {
  code: string;
  message: string;
  details?: Record<string, unknown>;
};

type NebulaHostCapabilityDescriptor = {
  supported: boolean;
  version: string;
};

type NebulaHostCapabilityMap = Record<string, NebulaHostCapabilityDescriptor>;

type PageLifecycleEvent = {
  appId: string;
  instanceId: string;
  routePath?: string;
  type: 'show' | 'hide' | 'unload';
};

type NebulaPageStyle = {
  backgroundColor?: string;
  navigationBarBackgroundColor?: string;
  navigationBarTextColor?: string;
  navigationBarTitleText?: string;
  navigationStyle?: 'default' | 'custom';
  visualEffectInBackground?: 'blur' | 'none';
};

type NavigationResult = {
  errMsg: string;
};

type HostVisibilityResult = {
  success: boolean;
  token?: string | null;
};

type ServerBaseURLResult = {
  serverBaseURL?: string | null;
};

Native Module

@nebula-rn/sdk communicates with the native layer via NebulaNativeModule.

Synchronous methods: getDeviceInfo()

Asynchronous methods: All other native calls return Promises.

Platform configuration constants:

Default timeouts:

Error code summary: