Skip to content

Store Packaging Distribution

Jump to bottom
Bobby Comet edited this page Jul 31, 2026 · 1 revision

Store, Packaging & Distribution Guidelines

Standards for shipping themes, plugins, and project graphs so others can run or remix them without path/plugin pain.

Three artifacts (pick by audience)

Artifact Audience Studio required?
Built theme folder End users who only run the HUD No — only Conky
Project JSON (+ assets) Authors remixing the graph Yes
Plugin manifest JSON Extending the palette Yes (to design); Conky runs the Lua

Public / store default: ship the built theme as the primary download. Attach JSON only if you want remixability.

Built theme package (recommended)

Layout

ThemeName/
├── theme.json          # name, author, version, description, resolution, requires
├── start.sh            # executable — single entry point
├── conky.conf
├── render.lua
├── images/             # all referenced bitmaps/SVGs
├── fonts/              # optional bundled fonts
├── scripts/            # daemon/exec helpers
├── preview.png         # optional screenshot
└── README.md           # human install notes

Rules

  1. Always include a working start.sh (Studio Build does this).
  2. No absolute paths to the author’s home directory inside conf/Lua/scripts.
  3. theme.json filled in (Manager can edit/generate).
  4. README states: distro notes, Wayland/X11 expectations, optional deps (playerctl, lm-sensors).
  5. Archive as .zip or .tar.gz of the folder contents (or the folder itself).
  6. Test on a clean machine or after renaming the folder: chmod +x start.sh && ./start.sh.

Install locations for users

Method Destination
Conky Studio Manager / Build & Install ~/.config/conky/ThemeName/
Manual Same tree, or user preference — still run via start.sh
Store tab Follow in-app install (copies into managed config tree when configured)

Project JSON sharing (remix)

Ship together

my-hud.json
assets/ or images/     # everything the graph references
scripts/               # custom scripts referenced by nodes
README-REMIX.md        # plugin list, Studio version, path notes

Checklist

Item Action
Plugins List type ids (logic.smooth, …) and pack URL or file
Paths Replace /home/you/... with relative or document re-link steps
Studio version Note minimum build if using new node types
Preview Build once yourself so recipients can compare behaviour

JSON alone is not a portable runtime. See Sharing Projects.

Plugin distribution

Manifest

  • api_version: "1.1" preferred
  • Unique ids: logic.* / visual.* per authoring rules
  • author, version, description, optional homepage / license

Channels

Channel How
Project plugins.json PR / publish to the default remote manifest
Local pack ~/.config/conky-studio/plugins/*.json
Store / community Link manifest URL in listing; users use Tools → Plugins…

Trust labeling

State clearly that plugin Lua runs inside Conky with theme-level privileges. Do not ship obfuscated packs.

Validation

from conkystudio.plugins.loader import load_manifest_file, validate_only
assert validate_only(load_manifest_file("my-pack.json")) == []

Store tab & community listings

When the Store feed is configured:

Expectation Detail
Primary file Built theme archive
Metadata Name, author, description, resolution, preview image
Optional Project JSON attachment for remixers
OpenDesktop / browser Catalog may open externally; install still lands in user config

If the Store is empty: check network, feed URL, and release channel — not necessarily a packaging error.

Compatibility labels (recommended in README)

Tested: X11 / Plasma Wayland / Hyprland
Not supported: GNOME Wayland overlays
Requires: conky (Wayland build if on Wayland), optional playerctl

Align with the Compatibility wiki.

Versioning

Piece Suggestion
Theme Semver in theme.json + folder name stability
Project JSON Note Studio version in README
Plugins Semver in each plugin entry; bump when Lua behaviour changes

Breaking plugin id renames force users to fix graphs — prefer additive ids.

What not to do

  • Ship only screenshots
  • Rely on author-machine absolute paths
  • Omit start.sh
  • Bundle untrusted plugin Lua without disclosure
  • Claim GNOME Wayland overlay support

Quick ship flow (authors)

  1. Finalize graph → Build to Folder (or Build & Install).
  2. Fill theme.json + README.
  3. Zip the theme directory.
  4. Optionally attach project JSON + plugin list for remixers.
  5. Publish to Store / Discord / GitHub Releases.

Clone this wiki locally