Publishing to the community

This assumes you already have a working mini tool built by following the mini tools guide. This page covers the path from "runs on my machine" to "any Finch user can install it in one click": packaging, publishing to npm, and (optionally) submitting to the official Finch community catalog.

The publishing model

Three layers to understand first — everything else follows from them:

1. npm is the only distribution channel. A mini tool is a standard npm package; package.json#finch is the only thing that sets it apart from an ordinary one. Once published to npm, anyone can install it with npx @finchtoys/minitools add <package-name> — no official Finch review required for this step.
2. The community catalog is an optional "featured slot," not a prerequisite for installing. The catalog data is a JSON file in the finchtoys/finch-releases repo (community/mini-tools.json), served through an edge-cached public read-only API at community.finchwork.app; the Finch client's "Community" panel reads it directly to render cards. A package not in this JSON can still be installed manually by name — it just won't show up in the recommendations.
3. Icons come from the npm package itself — no separate upload needed. When Finch displays an icon for an uninstalled community entry, it constructs https://unpkg.com/<npm-package>@<version>/icon.png directly — so icon.png must be published to npm at the package root, not just kept in your repo.

1. Pre-publish checks

npm run typecheck                   # No TypeScript errors
npx @finchtoys/minitools doctor .   # Static check on manifest / entry file
npm run build                       # dist/ is up to date

package.json#version follows semver — bump it manually or with npm version patch/minor/major before each release.

2. Only ship what's needed at runtime

Never publish source code. Use package.json#files as an allowlist (recommended) or .npmignore as a denylist:

{
  "files": [
    "dist/",
    "i18n/",
    "skills/",
    "icons/",
    "icon.png",
    "README.md"
  ]
}

3. Publish to npm

npm login
npm publish --access public   # Required for scoped packages

After publishing, anyone can run:

npx @finchtoys/minitools add <your-package-name>

To release an update:

npm version patch   # or minor / major
npm publish --access public

Users update with:

npx @finchtoys/minitools update <finch.id>

4. Recommended package.json structure

{
  "name": "@yourscope/finch-my-tool",
  "version": "0.1.0",
  "description": "One-sentence summary shown on the npm page",
  "main": "dist/index.js",
  "files": ["dist/", "i18n/", "skills/", "icons/", "icon.png", "README.md"],
  "scripts": {
    "build": "tsc",
    "prepublishOnly": "npm run build"
  },
  "devDependencies": {
    "@finchtoys/minitool-api": "latest",
    "typescript": "^5.0.0"
  },
  "finch": {
    "manifestVersion": 1,
    "id": "my-tool",
    "name": "My Tool",
    "main": "dist/index.js",
    "activationEvents": ["onStartup"],
    "categories": ["developer"],
    "contributes": { "tools": true }
  }
}

Key points:

• prepublishOnly guarantees a fresh build before every npm publish, so you never ship a stale dist/.
• @finchtoys/minitool-api is a types-only package — keep it in devDependencies. Finch injects the runtime; don't put it in dependencies.
• name (the npm package name) and finch.id (Finch's internal id) are different things: name can change, but finch.id should stay stable after the first release — it's the install directory name and the key used for permission records.
• For finch.categories, pick from the community catalog's supported categories: productivity / developer / creative / research / finance / commerce / education.

5. Submitting to the official community catalog

Before submitting, confirm the package is on npm and npx @finchtoys/minitools add <package-name> installs it successfully.

1. Make sure icon.png is in the npm package root: PNG format, 128×128 to 300×300 pixels (inclusive), and actually included in the published tarball (verify with npm pack --dry-run).
2. Open an issue in the official Finch release repo: https://github.com/finchtoys/finch-releases/issues
3. Tag it 小程序发布申请 (mini tool publishing request).
4. Include in the issue:
   • The npm package name
   • finch.id
   • A one-sentence description (shown directly on the community card)
   • Suggested category (one of the 7 above)
   • Confirmation that icon.png meets the spec
   • Whether it requires the user to configure an API key / permissions (helps reviewers assess risk level)
   • Screenshots or a demo GIF (optional, but strongly encouraged)

Once reviewed, the Finch team merges the entry into community/mini-tools.json. After that, users can discover and one-click install it from the toolbox's "Community" panel — no need to know the package name.

The installScope field on an official catalog entry determines the install button's default target (personal or global); unless stated otherwise, it defaults to personal — the same default as manual CLI installs.

6. Maintaining it after publishing

• Bug fix → bump patch, npm publish; users get it via CLI update, no need to reopen an issue.
• New feature → bump minor, update the README; if the community card description also needs to change, just add a comment to the original issue — no need for a new one.
• Breaking change → bump major, and document the migration steps in the README.
• End of maintenance → mark it deprecated with npm deprecate, and note it in the original submission issue.

Checklist

[ ] npm login verified
[ ] dist/ is up to date (npm run build)
[ ] files or .npmignore excludes src/ and build config
[ ] No .env / secrets in the package
[ ] finch.id is stable and matches the install directory name
[ ] prepublishOnly runs the build automatically
[ ] README explains what the mini tool does and any prerequisites
[ ] icon.png is in the package root, PNG, 128×128–300×300 pixels, included in the npm tarball
[ ] npm publish --access public succeeded
[ ] Verified install: npx @finchtoys/minitools add <package-name>
[ ] (Optional) Opened an issue on finch-releases to request catalog listing