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.
{
"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:
- The folder inside your zip must be named exactly like the
idof your app'sappInfo. - The
idof your app in awesome-apps'apps.jsonmust 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
.zipfile 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
distfolder, including themanifest.jsonthat 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.
{
"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:
idmust equal your app ID or end with it, separated by a dot (see App ID).versionsmust be sorted from newest to oldest.minOpenCloudis the lowest OpenCloud version your app supports.maxOpenCloudis optional and marks the highest supported OpenCloud version. Its patch component is ignored: for example,7.5.0allows all7.5.xversions.badgeis optional and accepts alabeland acolorofprimary,successordanger.screenshotsandresourcesare 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.pngwebApps/<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.