App Package Checklist

Shuuka app uploads are ZIP bundles. The platform installs the built package you upload. It does not inspect your source repo or run your build for you.

Bundle Layout

Your ZIP can contain the app files at the root or inside one top-level folder.

my-app.zip
├── manifest.json
├── index.html
├── icon.svg
├── thumbnail.jpg
├── header.jpg
├── settings.json
├── settings-global.json
├── inputs.json
├── lang/
│   ├── en.json
│   └── en/
└── assets/

Required Files

File	Required	Rule
manifest.json	Yes	Must contain at least name, version, and entry
entry file from manifest	Yes	The file referenced by manifest.json.entry must exist in the bundle
icon.svg	Yes	Must be a valid SVG
thumbnail.jpg	Yes	Must be a valid JPEG
header.jpg	Yes	Must be a valid JPEG and exactly 1000x263

Optional but Common Files

File	When to include it	What Shuuka uses it for
settings.json	App has owner-configurable public settings	Builds the App Global Settings page
settings-global.json	App needs secrets or owner-only configuration	Builds the secure App Global Settings page
groups and placeholders in manifest.json	App needs per-card sidebar configuration	Builds App Instance Settings
inputs.json	App collects submissions or structured data	Defines collected-data fields
lang/en.json	App has translatable UI strings	Translation tokens inside HTML pages
lang/{locale}/settings.json	App Global Settings UI needs translations	Localized labels for the App Global Settings page
lang/{locale}/settings-global.json	Secure App Global Settings UI needs translations	Localized labels for the secure App Global Settings page
screenshots/*	App needs marketplace screenshots	Preview images for the marketplace detail page

Build Rule

If you use React, Vue, or another bundler, upload the built output. Shuuka serves the generated files as-is.

Good pattern:

manifest.json
index.html
assets/app.js
assets/app.css
icon.svg
thumbnail.jpg
header.jpg

Bad pattern:

src/
vite.config.js
package.json

Runtime Files Shuuka Reads

These files are read directly by the platform when they are present.

File	Purpose
manifest.json	Marketplace metadata and runtime metadata
settings.json	App Global Settings schema
settings-global.json	Secure App Global Settings schema
inputs.json	Submission and collected-data schema

Before You Upload

• turn on Developer access in Settings > App preferences
• open the new app upload page
• make sure the ZIP contains the built app, not only source files
• make sure header.jpg is exactly 1000x263
• make sure entry points to the real built entry file
• make sure the manifest privacy block lists every third-party origin the app contacts or embeds
• make sure all secrets live in settings-global.json, not settings.json
• make sure every field key used in code matches the keys in your JSON schemas