Native · Package reference

@wrnexus/native

Cross-platform browser and Capacitor capability registry.

v0.8.7Private registryNative

Install the package

After WorkRoot approves private registry access, install the release-aligned package:

bun add @wrnexus/native@0.8.7

Request preview access. Never put registry tokens in source control.

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.

bun add @wrnexus/native

Usage

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.

Complete TypeScript API

Generated from the exact installed package declarations.

import { N as NativePlatform, a as NativeCapability, b as NativeRunOptions, c as NativeTarget } from './types-CDShWg0i.js';
export { d as NativeAdapter, e as NativeBrowserRuntime } from './types-CDShWg0i.js';
export { browserCapabilities } from './browser.js';
export { mobileCapabilities } from './mobile.js';

declare class NativeUnavailableError extends Error {
    constructor(message: string);
}
declare function isMobile(): boolean;
declare function platform(): NativePlatform;
declare function register<TOptions = unknown, TResult = unknown>(name: string, capability: NativeCapability<TOptions, TResult>): () => void;
declare function registered(): string[];
declare function supports(name: string, target?: NativeTarget): boolean;
declare function run<TResult = unknown>(name: string, options?: unknown, runOptions?: NativeRunOptions): Promise<TResult>;
declare function clearRegistry(): void;

type NativePermission = "camera" | "geolocation" | "microphone" | "notifications" | "photos" | "storage" | (string & {});
interface NativeCapabilityManifestEntry {
    name: string;
    description?: string;
    permissions?: NativePermission[];
    targets?: NativeTarget[];
    optional?: boolean;
}
interface NativeCapabilityManifest {
    name: string;
    version?: string;
    capabilities: NativeCapabilityManifestEntry[];
}
declare function defineNativeManifest<T extends NativeCapabilityManifest>(manifest: T): T;
declare function inspectNativeCapabilities(target?: NativeTarget): Array<{
    name: string;
    supported: boolean;
}>;
declare function missingNativeCapabilities(manifest: NativeCapabilityManifest, target?: NativeTarget): NativeCapabilityManifestEntry[];
interface PermissionAdapter {
    query(name: NativePermission): Promise<"granted" | "denied" | "prompt" | "unavailable">;
    request?(name: NativePermission): Promise<"granted" | "denied">;
}
declare class PermissionManager {
    private readonly adapter;
    constructor(adapter: PermissionAdapter);
    query(name: NativePermission): Promise<"denied" | "granted" | "prompt" | "unavailable">;
    ensure(name: NativePermission): Promise<boolean>;
}

declare const native: {
    isMobile: typeof isMobile;
    platform: typeof platform;
    register: typeof register;
    registered: typeof registered;
    run: typeof run;
    supports: typeof supports;
};

export { NativeCapability, type NativeCapabilityManifest, type NativeCapabilityManifestEntry, type NativePermission, NativePlatform, NativeRunOptions, NativeTarget, NativeUnavailableError, type PermissionAdapter, PermissionManager, clearRegistry, defineNativeManifest, inspectNativeCapabilities, isMobile, missingNativeCapabilities, native, platform, register, registered, run, supports };

Examples

Copy-ready examples from the installed package documentation.

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

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" },
);