Zum Hauptinhalt springen
Version: 7.2

Build and publish

This page describes how to build your app for production and how to publish it in the OpenCloud app store.

Building an app​

Run a production build:

pnpm build

The build writes your app into the dist folder. Static assets from a public folder are copied over as is. The result contains:

  • js/<name>-<hash>.mjs - the entry point of your app, plus its chunks.
  • manifest.json - the metadata that OpenCloud uses to discover and load your app.
  • any static assets of your app.

The generated manifest.json is your src/manifest.json plus the entrypoint key, which the build sets. Only entrypoint is required by the server. Add any other metadata of your app to src/manifest.json yourself.

dist/manifest.json
{
"name": "my-app",
"version": "1.0.0",
"description": "My OpenCloud app",
"entrypoint": "js/my-app-a1b2c3d4.mjs"
}

Publishing in the app store​

Apps in the OpenCloud app store are listed in the awesome-apps repository. Publishing means adding your app to its webApps/apps.json file via a pull request.

App ID​

OpenCloud identifies an installed app by the name of its folder in the web application directory. To match installed apps against the app store, the following IDs must line up:

  1. The folder inside your zip must be named exactly like the id of your app's appInfo.
  2. The id of your app in awesome-apps' apps.json must either equal this ID or end with it, separated by a dot.

For example, an app with the appInfo.id my-app ships a zip containing a my-app folder and is listed in apps.json as com.github.my-org.my-repo.my-app. If your appInfo.id is already namespaced, e.g. com.github.my-org.my-app, use that exact ID for both the folder and the apps.json entry.

Requirements​

  • Your app must be downloadable as a .zip file from a stable URL, for example a GitHub release asset.
  • The zip must contain a single folder named after your app ID (see App ID). That folder holds the content of your dist folder, including the manifest.json that a production build produces. Admins copy this folder into their web application directory as is.

apps.json entry​

Add one entry under the apps key. The schema is defined in the app store types.

webApps/apps.json
{
"id": "com.github.my-org.my-repo.my-app",
"name": "My App",
"subtitle": "One short line about what the app does.",
"description": "A longer description.",
"license": "Apache-2.0",
"versions": [
{
"version": "1.0.0",
"minOpenCloud": "7.2.0",
"url": "https://github.com/my-org/my-repo/releases/download/v1.0.0/my-app-1.0.0.zip"
}
],
"authors": [{ "name": "My Organization", "url": "https://example.org" }],
"tags": ["editor", "viewer"],
"coverImage": {
"url": "https://raw.githubusercontent.com/opencloud-eu/awesome-apps/main/webApps/my-org/my-repo/cover.png"
},
"screenshots": [
{
"url": "https://raw.githubusercontent.com/opencloud-eu/awesome-apps/main/webApps/my-org/my-repo/screenshots/1.png",
"caption": "What this screenshot shows"
}
],
"resources": [
{ "url": "https://github.com/my-org/my-repo", "label": "Source code", "icon": "github" }
]
}

Notes on the fields:

  • id must equal your app ID or end with it, separated by a dot (see App ID).
  • versions must be sorted from newest to oldest. minOpenCloud is the lowest OpenCloud version your app supports. maxOpenCloud is optional and marks the highest supported OpenCloud version. Its patch component is ignored: for example, 7.5.0 allows all 7.5.x versions.
  • badge is optional and accepts a label and a color of primary, success or danger.
  • screenshots and resources are optional.

Assets​

Cover image and screenshots are stored in the awesome-apps repository. Use a 3:2 aspect ratio and prefer PNG or JPEG.

Follow this folder structure:

  • webApps/<org-name>/<repo-name>/cover.png
  • webApps/<org-name>/<repo-name>/screenshots/1.png

If your repository hosts several apps, add the app name to the path, for example webApps/<org-name>/<repo-name>/<app-name>/cover.png.

Make sure the license of your assets allows us to keep them in the repository and to show them in the app store. If you are not sure about the license of an asset, do not add it.