miniapp.yaml Configuration

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

If miniapp.yaml is not 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"

orientation: "portrait"

---

menuButton

Controls the floating menu button shown on top of your mini-app. This button allows users to return to the main application or access other platform features.

Field	Type	Default	Description
enabled	boolean	true	Show or hide the menu button
opacity	number	1.0	Button transparency (0.0 - 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 inside your mini-app.

---

externalRuntime

If your mini-app uses a shared external runtime (e.g. a game engine), you can declare it here. The platform will inject the runtime JS from a shared cache instead of your ZIP bundle.

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, the file is downloaded once and shared across all mini-apps using 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 from the ZIP and reduces its size.

2. Download: When a user opens your mini-app, the platform injects the runtime JS from the local cache. If the file is not cached, the original JS inside your ZIP 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"

Uses Godot v4.2 and godot.js — all defaults.

Godot game with a specific version:

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

Three.js mini-app:

externalRuntime:
  name: "threejs"

WARNING

Make sure version and fileName match the actual runtime files your mini-app was built with. Version mismatches can cause runtime errors.

INFO

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

---

orientation

Sets the screen orientation preference for your mini-app. The platform reads this value and automatically locks or unlocks the device screen when the mini-app opens. When the mini-app closes, the orientation always restores to the default (unlocked).

Value	Description
"portrait"	Always portrait — stays vertical even if the user rotates the device
"landscape"	Always landscape — stays horizontal even if the user rotates the device
"auto"	Follows the device sensor — rotates freely based on how the user holds the phone

Default: "auto"

Examples

Always portrait (card games, puzzle games, etc.):

orientation: "portrait"

Always landscape (racing, platformers, etc.):

orientation: "landscape"

Follow device orientation (default — no need to add to YAML):

orientation: "auto"

TIP

If your game is designed to be played in landscape mode, use "landscape". Even if the user holds the phone upright, the game will be shown in landscape.

INFO

If orientation is not specified, "auto" is applied — the screen rotates freely based on device position.

WARNING

orientation only applies to mini-apps loaded in ZIP mode that include a miniapp.yaml. It can also be changed at runtime via the JavaScript Bridge (setOrientation).

---

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/
│   └── ...
└── ...