Wox Plugin Submit2store
Overview
Submit a plugin to the Wox store through a PR against Wox-launcher/Wox. Ensure a reusable fork exists first, read local plugin metadata, refuse duplicate submissions, and only modify store-plugin.json when the plugin ID is not already present. A store entry requires at least one public screenshot. Do not submit with an empty or omitted ScreenshotUrls, and do not open a PR that says a screenshot will be added later.
For single-file SDK plugins, host the plugin on a public GitHub gist. That is the simplest store delivery. Do not require a GitHub repository, plugin.json, or a .wox package. Example: https://gist.github.com/qianlifeng/04a9609de66eaa582a473f5852450ede
Workflow
- Ensure the user already has a fork of
Wox-launcher/Wox, or create one. - Read the current plugin (packaged repo, or the single-file
.js/.pyheader) before touching the store repo. - Validate that the plugin has enough public metadata and release assets for a store entry, including at least one public screenshot of the plugin running in Wox.
- Clone the user's fork into a temporary directory and add
upstreamforhttps://github.com/Wox-launcher/Wox. - Check upstream
store-plugin.jsonfor the current plugin ID. - Stop and tell the user not to submit when the ID already exists.
- Add the new store entry when the ID is absent.
- Commit on a branch in the fork and open a PR to
Wox-launcher/Wox.
Ensure A Fork Exists First
Treat fork setup as the first gate. Do not clone or edit a working copy until one of these is true:
- the user already has a fork of
Wox-launcher/Wox - the current authenticated GitHub user can create one now
Use this order:
- Check whether the user already has a fork and reuse it when present.
- If
ghis available and authenticated, create the fork from the CLI. - If
ghis unavailable, unauthenticated, or fails, send the user to the web fork flow and continue only after the fork exists.
For CLI-driven fork handling:
- prefer reusing an existing fork instead of creating a new one
- if a fork is missing, create it with GitHub CLI
- after the fork exists, treat the fork as
originand the official repo asupstream
For web fallback:
- direct the user to
https://github.com/Wox-launcher/Wox/fork - wait for the user to confirm the fork is ready
- continue by cloning the fork repository, not the upstream repository
When the user has direct write access to Wox-launcher/Wox, a fork is not required. Otherwise, do not assume direct push access.
Read Local Metadata First
For a single-file SDK plugin, read the JSON metadata header in the live .js or .py file (usually ~/.wox/wox-user/plugins/single-file/Wox.Plugin.<Name>.js). Prefer a public gist as Website / DownloadUrl. Upload the screenshot and icon to GitHub and use https://gist.github.com/user-attachments/assets/<id> URLs for IconUrl and ScreenshotUrls.
For a packaged SDK plugin, read at least:
plugin.jsonpackage.jsonwhen version information needs confirmation- local screenshots or icon files when URLs need to be derived
- git remotes to determine the GitHub repository URL
Extract or derive these values:
- plugin
Id NameAuthorVersionMinWoxVersionRuntimeDescriptionWebsite(gist HTML URL, or GitHub repository URL)DownloadUrl(gist raw.js/.pyURL, or.woxrelease asset)- public icon URL
- required screenshot URLs: at least one public image of the plugin running in Wox
- supported operating systems
Stop and ask the user to fix the source first when any of these conditions hold:
- metadata still contains template placeholders such as
{{.Id}}or{{.Name}} - a single-file plugin has no public gist whose raw URL path ends with
.jsor.py - a packaged plugin has no public repository URL or no installable
.woxrelease asset - there is no screenshot,
ScreenshotUrlswould be empty or omitted, or the only screenshot is local and has no stable public URL - the icon is only local and no stable public URL can be formed
Clone The Fork And Check For Duplicates
Clone the user's fork into a temporary directory instead of modifying the current plugin workspace. Add the official repository as upstream so the branch and PR target remain Wox-launcher/Wox.
Inspect store-plugin.json from the current upstream default branch and search by the exact plugin ID from the local metadata.
When the ID already exists:
- do not modify
store-plugin.json - tell the user that the plugin is already listed
- include the existing matching entry or its location so the user can verify it quickly
When the ID does not exist:
- continue to create a new entry
- preserve the file's existing formatting and ordering style
Build The Store Entry
Use the field template and sourcing rules in references/store-plugin-entry.md.
Apply these rules while building the JSON object:
- Keep
Id,Name,Author,Version,MinWoxVersion, andRuntimealigned with local plugin metadata. - Prefer a plain
Descriptionstring when no i18n payload exists. - Add
I18nonly when the repository already has trustworthy localized copy. - Convert local OS names to the store style:
Windows,Darwin,Linux(Macosin plugin headers becomesDarwin). - Set
DateCreatedandDateUpdatedto the current local timestamp inYYYY-MM-DD HH:MM:SS. - For a gist-hosted single-file plugin:
Websiteis the gist HTML URL,DownloadUrlis the gist raw URL including the.jsor.pyfilename, andIconUrl/ScreenshotUrlsarehttps://gist.github.com/user-attachments/assets/<id>links. Runtime is lowercasenodejsorpython. - For a packaged plugin: use the canonical repository URL for
Website, the latest.woxrelease asset forDownloadUrl, and public raw image URLs forIconUrl/ScreenshotUrls. ScreenshotUrlsmust contain at least one public URL. Do not omit the field, submit[], or continue while telling the user that no screenshot is included yet. Ask for a screenshot and stop until one is uploaded. Use a cropped Wox launcher screenshot that shows the query and the plugin's real results, like https://raw.githubusercontent.com/Wox-launcher/Wox.Plugin.ColorPicker/main/images/screenshot1.png. Do not submit an icon, a README image, source code, or a full-desktop capture.
Before editing store-plugin.json, re-check that the generated URLs and filenames match the gist file name or the packaged repository layout.
Prepare The PR
After editing the cloned fork workspace:
- Create a branch such as
codex/add-<plugin-name>-store-entry. - Commit only the
store-plugin.jsonchange. - Push to the user's fork.
- Open a PR targeting
Wox-launcher/Wox.
Use a concise PR title such as Add <Plugin Name> to store.
Use a PR body that includes:
- what plugin was added
- the gist or repository URL
- the download URL
- every public screenshot URL. Stop instead of opening the PR when this list is empty
Report Back To The User
Always end with one of these outcomes:
Already listed: explain that no submission is needed.Ready to submit: summarize the new store entry and PR URL.Waiting for fork: tell the user to finish the web fork flow before continuing.Blocked: list the missing metadata or missing public assets that prevented submission.