This guide will walk you through the process of publishing your app or theme to the Bruce App Store repository.
Before you can publish an app or theme, you’ll need:
/BruceJS/<category>/ directory - use __dirpath to reference the folder the script is being ran from if your app needs access to other files/BruceThemes/<theme name> folderApps/themes in the Bruce App Store are organized as follows:
repositories/
└── [your-github-username]/
└── [your-repository-name]/
└── [Your App/Theme Name]/
├── metadata.json
└── logo.png
Navigate to the repositories folder and create the following structure:
repositories/[your-github-username]/[your-repository-name]/[Your App/Theme Name]/
For example:
repositories/johndoe/my-awesome-apps/WiFi Scanner/
The metadata.json file contains all the essential information about your app/theme. Create this file in your app/theme directory with the following structure:
{
"name": "Your App/Theme Name",
"description": "A brief description of what your app/theme does",
"category": "Tools",
"version": "1.0.0",
"commit": "40-character-sha-hash-from-your-repository",
"owner": "your-github-username",
"repo": "your-repository-name",
"path": "/path/to/files/in/your/repo/",
"files": [
"file1.js",
{
"source": "file2.js",
"destination": "file-two.js"
}
]
}
| Field | Type | Description | Example |
|---|---|---|---|
name |
String | Display name of your app/theme | “WiFi Scanner” |
description |
String | Brief description of functionality | “Scans for available WiFi networks” |
category |
String | App/theme category (see valid categories below) | “WiFi” |
version |
String | Semantic version (X.Y.Z format) | “1.0.0” |
commit |
String | Exact 40-character SHA hash from your repo | “a1b2c3d4e5f6…” |
owner |
String | Your GitHub username | “johndoe” |
repo |
String | Your repository name | “my-awesome-apps” |
path |
String | Path to files in your repository | ”/” or “/apps/” |
files |
Array | List of files to include | See Files Array section below for details |
| Field | Type | Description | Example |
|---|---|---|---|
supported-devices |
String or Array | Device compatibility (apps only, not themes) | See Supported Devices section below |
| Field | Type | Description | Example |
|---|---|---|---|
supported-screen-size |
String | Screen dimensions in widthxheight format | “320x170” |
Your app must use one of these categories, if submitting a theme please use the Theme category:
AudioBluetoothGamesGPIOInfraredMediaRFIDRFThemes - Only for themesToolsUSBUtilitiesWiFiThe files array can contain:
Simple file paths (strings):
"files": [
"my-app.js",
"config.txt"
]
File mapping objects (for renaming during installation):
"files": [
{
"source": "my_long_filename.js",
"destination": "app.js"
}
]
Mixed array of both types:
"files": [
"readme.txt",
{
"source": "main_application.js",
"destination": "app.js"
}
]
The supported-devices field is optional for apps/scripts and allows you to specify which devices your app is compatible with. This field is not allowed for themes. If not specified for an app, it will be available for all devices.
This field supports three formats:
"supported-devices": "M5Stack Cardputer"
"supported-devices": [
"M5Stack Cardputer",
"Lilygo T-Embed",
"M5Stack Core 2"
]
"supported-devices": "M5Stack.*"
Common regex patterns:
"M5Stack.*" - All M5Stack devices"CYD-.*" - All CYD (Cheap Yellow Display) devices"Lilygo.*" - All Lilygo devices".*Cardputer.*" - Any device with “Cardputer” in the nameValid device names can be found in supported-devices.json.
The supported-screen-size field is required for themes and specifies the screen dimensions that the theme is designed for.
Format: "widthxheight" where width and height are positive integers.
Examples:
"320x170" - For devices with 320x170 pixel screens"240x135" - For devices with 240x135 pixel screens"480x320" - For devices with 480x320 pixel screens"supported-screen-size": "320x170"
Your app/theme needs a logo file named exactly logo.png:
logo.png (lowercase)Before your app/theme is approved, it will be automatically validated for:
metadata.json exists and is valid JSONlogo.png exists and is a valid PNG file (64x64 to 512x512, square)repositories/owner/repo/ formatfiles array exist at the specified commitmetadata.json and logo.png filesOnce you submit your PR:
review required - Ready for manual reviewmissing metadata.json - metadata.json file missinginvalid metadata.json - metadata.json has errorsmissing logo.png - logo.png file missingexternal contribution - Submitted by external contributorIf validation passes:
To update an existing app/theme:
⚠️ Important: You must update both version AND commit hash for updates.
Here’s a complete example for a WiFi scanner app:
Folder structure:
repositories/johndoe/bruce-tools/WiFi Scanner/
├── metadata.json
└── logo.png
metadata.json:
{
"name": "WiFi Scanner",
"description": "Comprehensive WiFi network scanner with signal strength display",
"category": "WiFi",
"version": "1.2.0",
"commit": "a1b2c3d4e5f6789012345678901234567890abcd",
"owner": "johndoe",
"repo": "bruce-tools",
"path": "/wifi-apps/",
"supported-devices": [
"M5Stack Cardputer",
"Lilygo T-Embed"
],
"files": [
{
"source": "wifi_scanner_main.js",
"destination": "scanner.js"
},
"config.json"
]
}
Here’s an example for a dark theme:
Folder structure:
repositories/johndoe/bruce-themes/Dark Theme/
├── metadata.json
└── logo.png
metadata.json:
{
"name": "Dark Theme",
"description": "A sleek dark theme for Bruce devices",
"category": "Themes",
"version": "1.0.0",
"commit": "b2c3d4e5f6789012345678901234567890abcdef",
"owner": "johndoe",
"repo": "bruce-themes",
"supported-screen-size": "320x170",
"path": "/themes/",
"files": [
"wifi.gif",
...
"config.gif",
"theme.json"
]
}
| Error | Cause | Solution |
|---|---|---|
| “Missing required field” | Required field is empty or missing | Add all required fields to metadata.json |
| “Version must be in format X.Y.Z” | Invalid version format | Use semantic versioning (e.g., “1.0.0”) |
| “Commit must be a valid 40-character SHA hash” | Wrong commit format | Use full 40-character commit hash |
| “Category is not in valid list” | Invalid category | Use one of the valid categories listed above |
| “Folder structure invalid” | Wrong directory structure | Place app/theme in repositories/owner/repo/AppName/ |
| “File not found at commit” | File doesn’t exist in repository | Ensure all files in files array exist at the commit |
| “Version must be incremented” | Version not updated for existing app/theme | Increase version number for updates |
| “supported-screen-size is required for themes” | Missing screen size for theme | Add supported-screen-size field with format “widthxheight” |
| “supported-screen-size must be in format ‘widthxheight’” | Invalid screen size format | Use format like “320x170” |
| “supported-screen-size is only allowed for themes” | Used screen size on non-theme | Remove supported-screen-size field or change category to Themes |
| “supported-devices is not allowed for themes” | Used supported-devices on theme | Remove supported-devices field from themes |
| “Device not in supported devices list” | Invalid device name in supported-devices | Use device names from supported-devices.json |
| “Regex pattern doesn’t match any devices” | Regex doesn’t match any valid devices | Verify regex pattern matches at least one device |
If you encounter issues:
Ready to publish? Follow the steps above and submit your Pull Request! 🚀