Skip to content

store-config.md

Latest commit

 

History

History
149 lines (105 loc) · 4 KB

store-config.md

File metadata and controls

149 lines (105 loc) · 4 KB
Raw

Store Config

store-config.json defines store identity at the repository level.

Purpose

The build script reads store-config.json and generates:

  • dist/store.json
  • dist/store.{locale}.json for locales explicitly defined in store localized text fields

Minimal example

{
  "version": 2,
  "store_id": "my-awesome-apps",
  "name": {
    "en_US": "My Awesome Apps",
    "zh_CN": "我的应用商店"
  },
  "description": {
    "en_US": "A collection of apps for home server enthusiasts"
  },
  "maintainer": "your-github-username",
  "url": "https://github.com/username/my-appstore"
}

Fields

Field Type Required Notes
version int Yes Must be 2
store_id string Yes Unique store identifier
name object Yes Locale-keyed display name
description object No Locale-keyed store description
maintainer string Yes Maintainer or owner name
url string No Project or homepage URL
icon string No Store icon URL

Field reference

version

  • required
  • must be the integer 2
  • identifies the source protocol version used by the build flow

store_id

  • required
  • primary identity of the store
  • should remain stable after users start subscribing
  • should be chosen as a globally distinctive value

name

  • required
  • must be a locale-keyed object, not a plain string
  • should always include en_US
  • becomes the display name in generated store.json

description

  • optional
  • locale-keyed object
  • useful for store overview text shown in clients

maintainer

  • required
  • plain string naming the store maintainer, owner, or organization

url

  • optional
  • public project, repository, or homepage URL

icon

  • optional
  • public store-level icon URL
  • unlike per-app assets, this is not generated from an app directory asset pipeline

store_id rules

  • letters, digits, ., _, and - only
  • uppercase input is allowed but normalized to lowercase
  • must contain at least one letter or digit
  • must be globally distinctive
  • do not use reserved values such as zimaos-appstore

Validation expectations

Treat these as source contract rules:

  • the file must be valid JSON
  • version must match the active protocol version
  • name should be an object
  • locale keys should use ll_CC format
  • URL fields should already be public and reachable

Localization behavior

The build script resolves store-level localized text from:

  • name
  • description

Only locales explicitly defined in these fields are emitted as store.{locale}.json.

Output behavior

The build script always emits a default-locale file:

  • dist/store.json

It additionally emits locale-suffixed files only when that locale is explicitly present in store localized text:

  • dist/store.zh_CN.json
  • dist/store.de_DE.json

This keeps the output small while still supporting localized store metadata.

Input to output mapping

Source field Generated location Notes
version store.json.version carried through as protocol metadata
store_id store.json.store_id normalized during build if needed
name.<locale> store.{locale}.name resolved per locale file
description.<locale> store.{locale}.description emitted only for explicit locales
maintainer store.json.maintainer copied as plain string
url store.json.url copied as plain string
icon store.json.icon copied as plain string URL

Practical guidance

  • Always provide name.en_US
  • Add description when the store needs a visible introduction in the client
  • Keep store_id stable once users start subscribing to your store

Common mistakes

  • writing name as a plain string instead of a locale-keyed object
  • changing store_id after clients already use the store
  • using locale keys like en_us instead of en_US
  • assuming every locale in supported-languages.json will automatically produce store.{locale}.json