miniapp-selfhost-sync

A Bun-first CLI for self-hosting remote miniapp bundles.

Runtime requirement

This tool is designed to run with Bun.

• Required: bun >= 1.1.0
• Node.js direct execution is not the target runtime for this package.

What it does

• pulls metadata.json, source.json, and the latest .miniapp.zip
• unpacks files to a local miniapp/ directory
• rewrites url, icon, and optional website to your own host
• stores local sync state and skips unchanged versions
• generates both full nginx config and include snippets (N+1)
• supports polling mode (default every 30s)

Install

npm i -g miniapp-selfhost-sync

Or use without global install:

bunx miniapp-selfhost-sync --help

Quick start

1. Initialize config template to current directory:

miniapp-selfhost-sync --init

This creates ./miniapp-selfhost-sync.config.json.

2. Edit it and run once:

miniapp-selfhost-sync --config ./miniapp-selfhost-sync.config.json --once

3. Run polling mode:

miniapp-selfhost-sync --config ./miniapp-selfhost-sync.config.json

Config example

{
  "intervalMs": 30000,
  "requestTimeoutMs": 20000,
  "resourceHost": "https://miniapp-source.example.com/",
  "entries": [
    {
      "name": "app-a",
      "routePath": "hub",
      "enabled": true,
      "rawSourceUrl": "https://source-a.example.com/",
      "miniappHost": "https://hub.example.com/",
      "website": "https://www.example.com/",
      "outputDir": "./mirror/hub"
    }
  ]
}

CLI options

--config <path>    Config file path (default: ./miniapp-selfhost-sync.config.json)
--once             Run one sync pass and exit
--dry-run          Check updates only; do not write files
--init             Write miniapp-selfhost-sync.config.json to current directory
--force            Used with --init; overwrite existing file
--help             Show help

Config fields

Entry object fields:

• name: Optional display name in logs.
• routePath: Optional route segment on resource host, e.g. hub -> /hub/source.json.
• enabled: Optional, defaults to true.
• entryUrl / rawSourceUrl: at least one is required.
• miniappHost: target public host URL.
• website: optional override for website in manifest/source.
• outputDir: local output directory.

Top-level optional fields:

• resourceHost: domain used for subscription routes such as /hub/source.json.

Output layout

For each entry:

• metadata.json
• source.json
• manifest-<version>.json
• <id>-<version>.miniapp.zip
• miniapp/ (unzipped current bundle)
• .miniapp-sync-state.json

For resource host (N+1):

• <config-dir>/_nginx/apps/<entry-route>/README.md
• <config-dir>/_nginx/apps/<entry-route>/nginx-miniapp.v<sync-version>.conf
• <config-dir>/_nginx/apps/<entry-route>/nginx-miniapp.v<sync-version>.inc.conf
• <config-dir>/_nginx/resource/README.md
• <config-dir>/_nginx/resource/nginx-resource.v<sync-version>.conf
• <config-dir>/_nginx/resource/nginx-resource.v<sync-version>.inc.conf
• <config-dir>/_nginx/all/README.md
• <config-dir>/_nginx/all/nginx-all-in-one.v<sync-version>.inc.conf

Both nginx files include the sync script version in file name. The same version will not overwrite existing files.

License

MIT