WRNexusJS/packages/native

@wrnexus/native

Cross-platform capabilities for browsers, Capacitor WebViews, and compiled native apps.

Overview

@wrnexus/native exposes capabilities by name so application code can ask what the current platform supports before presenting an action. Browser capabilities use Web APIs; mobile capabilities use installed Capacitor plugins. platform() returns "server" during SSR, "browser" on the web, and the Capacitor platform in a native WebView.

Installation

bun add @wrnexus/native

Usage

Share a page when the platform supports it

import { native } from "@wrnexus/native";

export async function shareCurrentPage() {
  if (!native.supports("share")) return false;
  await native.run("share", {
    title: document.title,
    url: location.href,
  });
  return true;
}

Register an application-specific capability

register returns an unregister function, which is useful for tests and temporary feature modules.

import { native } from "@wrnexus/native";

const unregister = native.register("orders.scan", {
  browser: {
    supported: () => typeof window !== "undefined",
    run: async ({ orderId }: { orderId: string }) => {
      const code = window.prompt(`Scan code for order ${orderId}`);
      return { code };
    },
  },
});

const result = await native.run<{ code: string | null }>("orders.scan", { orderId: "ord_42" });
unregister();

Target browser or mobile behavior explicitly

import { native } from "@wrnexus/native";

const canUseMobileCamera = native.supports("camera", "mobile");
const position = await native.run(
  "geolocation",
  { enableHighAccuracy: true },
  { target: "browser" },
);

API

• supports(name, target?) checks availability without running the capability.
• run(name, options?, runOptions?) executes it or rejects with NativeUnavailableError.
• register(name, capability) adds or overrides a capability and returns cleanup.
• registered() lists capability names; clearRegistry() resets the registry.
• isMobile() and platform() report the current target safely during SSR.

Built-ins include camera, clipboard.write, share, geolocation, network, haptics, storage, filesystem, notifications, and device information.

defineNativeManifest declares required capabilities and typed permissions, while PermissionManager normalizes permission query/request flows across platform adapters.

Requirements / Notes

Use supports() before showing optional controls. Mobile capabilities require their matching Capacitor plugins to be installed and registered by the application.