Mobile Converter

Prepare an existing web frontend for Android and iOS packaging.

Availability and installation

This guide covers @wf/mobile-converter version 0.3.0-alpha.4, currently a preview. The catalog does not verify public registry installation for this version. Obtain the matching package and dependencies through the delivery method shown on its product page. Do not infer that an unlisted package can be installed from the public npm registry.

App-specific native Capacitor plugins can be included through app.nativePlugins in the same YAML file. Each entry requires its npm name, a local .tgz archive path resolved relative to the YAML file, and its exact lowercase SHA-256 as sha256. Archives must remain inside the allowed project and be no larger than 10 MiB; at most eight unique plugins are allowed. The converter verifies and copies these immutable archives during prepare, installs them during sync with package scripts disabled, and retains verified previous archives for rollback. The host reviews the native code and owns its consent, credentials, and domain behavior; the SDK owns the packaging mechanism. Overrides of Capacitor's own packages and unknown settings are rejected.

For an update, set app.version (for example, 1.2.3) and app.buildNumber (for example, 5) together in YAML. Sync applies both to Android and iOS; verify and build reject stale native version settings. Choose a new version/build before distributing an update. Existing configurations without these fields preserve their native version settings. Custom dynamic version expressions require host review and are never overwritten.

The supported runtime, exported entry points, and compatibility commitments are listed in Compatibility. Check Release notes before upgrading.

Configure and use

Keep SDK settings in a YAML file and pass its path to the package’s public client. Keep credentials in application-owned secret storage; configuration examples contain references, not secret values.

After building the web frontend, save this as mobile.config.yaml beside the project. Change webDir if its build output uses another folder; inspection and preparation use the same setting.

workspaceRoots: [.]
allowBuilds: false
app:
  appId: com.example.notes
  appName: Notes
  webDir: dist
  platforms: [android, ios]
  # backendOrigin: https://your-app.example

The delivered package includes examples/buyer.mjs and examples/mobile.config.yaml. The default client needs no legacy package or WF installation:

import { createMobileConverter } from '@wf/mobile-converter';
const converter = createMobileConverter('./mobile.config.yaml');
try {
  await converter.prepare(process.cwd());
  console.log(await converter.verify(process.cwd()));
} finally {
  await converter.dispose();
}

The example leaves native builds disabled. Enabling builds runs trusted project build scripts; signing, service accounts, store submission, and distribution remain the host’s responsibility.

The converter packages web assets; it does not rewrite arbitrary desktop applications or run their backend on a phone. API-dependent apps need a reachable backend and the package’s browser/customer adapter or an application-specific equivalent. A verified asset bundle does not establish a signed, store-ready application.

Integration responsibilities

The application owns user authorization, credential storage, and permission to make external calls. Review the example before running it: a connected provider or an update action can have real effects. Preserve the package’s cancellation and disposal behavior where those APIs are exposed.

Preview compatibility is limited to the combinations actually recorded in Compatibility. An empty verified-combinations list is not a promise that every platform or client has been tested.