---
title: "Publishing to the community · Finch Agent"
description: "Publish a mini tool to npm and the Finch community"
source: https://finchwork.app/en/docs/minitools-publishing
---

# Publishing to the community

This assumes you already have a working mini tool built by following the [mini tools guide](/en/docs/minitools). 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

```bash
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:

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

| Path | Publish? | Why |
| --- | --- | --- |
| `dist/` | ✅ Required | The compiled runtime entry |
| `icon.png` | ✅ Required | The community catalog icon comes from the npm package (see above) |
| `i18n/` / `skills/` / `icons/` | ✅ If used | Only needed if the corresponding feature is used |
| `README.md` | ✅ Recommended | Shown on the npm page and in the community card detail |
| `src/`, `tsconfig.json`, tests, `.env*` | ❌ Never | Not needed at runtime; `.env*` especially must never contain secrets |

## 3\. Publish to npm

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

After publishing, anyone can run:

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

To release an update:

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

Users update with:

```bash
npx @finchtoys/minitools update <finch.id>
```

## 4\. Recommended `package.json` structure

```json
{
  "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](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
```