miniapp.yaml Configuration

Every mini-app can include a miniapp.yaml file in the root of its ZIP package. This file controls how the platform loads and displays your mini-app.

If no miniapp.yaml is present, default values are used.

Full Example

menuButton:
  enabled: true
  opacity: 1.0
  color: "#6200EE"
  position: "top-right"

externalRuntime:
  name: "godot"
  version: "4.2"
  fileName: "godot.js"

---

menuButton

Controls the floating menu button overlay that appears on top of your mini-app. This button allows users to go back to the host app or access other platform features.

Field	Type	Default	Description
enabled	boolean	true	Show or hide the menu button
opacity	number	1.0	Button opacity (0.0 to 1.0)
color	string	platform default	Hex color code (e.g. "#6200EE")
position	string	"top-right"	Button position on screen

Position Values

Value	Description
"top-right"	Top-right corner
"top-left"	Top-left corner
"bottom-right"	Bottom-right corner
"bottom-left"	Bottom-left corner

Examples

Hide the menu button:

menuButton:
  enabled: false

Semi-transparent button in the bottom-left:

menuButton:
  enabled: true
  opacity: 0.5
  color: "#FF5722"
  position: "bottom-left"

TIP

If you hide the menu button (enabled: false), make sure your mini-app provides its own way for users to exit. Otherwise, users may get stuck in your mini-app.

---

externalRuntime

If your mini-app uses a shared external runtime (such as a game engine), you can declare it here. The platform will provide the runtime JS file from a shared cache instead of bundling it in your ZIP.

This significantly reduces your mini-app's download size. For example, Godot's runtime JS (godot.js) is ~30MB — by declaring it as an external runtime, it's downloaded once and shared across all mini-apps that use the same engine.

Field	Type	Required	Default	Description
name	string	yes	—	Runtime identifier
version	string	no	engine default	Runtime version
fileName	string	no	engine default	Runtime JS file name

Supported Runtimes

Name	Default Version	Default File Name
godot	4.2	godot.js
threejs	r158	three.min.js

How It Works

1. Upload: When you upload your mini-app ZIP with externalRuntime declared, the platform automatically strips the runtime JS file from the ZIP to reduce its size.

2. Download: When a user opens your mini-app, the platform injects the runtime JS from a locally cached copy. If the cached file is not available, the original bundled JS is used as a fallback.

3. Shared cache: The runtime JS is downloaded once per device and shared across all mini-apps using the same runtime and version.

Examples

Godot game with defaults:

externalRuntime:
  name: "godot"

This uses Godot v4.2 with godot.js — all defaults.

Godot game with specific version:

externalRuntime:
  name: "godot"
  version: "4.3"
  fileName: "godot.js"

Three.js mini-app:

externalRuntime:
  name: "threejs"

WARNING

Make sure the version and fileName match the actual runtime files your mini-app was built with. A version mismatch may cause runtime errors.

INFO

If you don't declare externalRuntime, the platform assumes the runtime JS is bundled in your ZIP and no optimization is applied. Your mini-app will work either way.

---

File Location

The miniapp.yaml file must be placed at the root of your ZIP package:

your-miniapp.zip
├── index.html
├── miniapp.yaml      ← here
├── game.js
├── assets/
│   └── ...
└── ...