Publishing

You can share a plugin in two ways. Publish it to the store, where anyone with a Flare account can publish and anyone can install in one click. Or share it by hand, as a .tgz file or an npm package. Either way, users see every scope the plugin asks for before it installs.

The store

Published plugins are listed at flare.tools/plugins and in the app under Settings, Plugins, Discover. Each plugin gets a page with its description, README, scopes, versions and download count.

Downloads count once per user or address, per plugin, per day. The number reflects how many people use a plugin, not how often it updates.

Installing from the store

Users install a store plugin in one of three ways:

• Discover, in Settings, Plugins: search, filter by kind, and press Install on a card or on the plugin's page.
• Install in Flare on the plugin's page at flare.tools/plugins.
• A link to flare://plugins/install/<id>, anywhere. Add ?version=1.2.0 to install that version.

[Install in Flare](flare://plugins/install/flare.stripe)

Flare downloads the package through the store, checks it against the hash the store sent with it, and checks that it's the plugin the link named. Then it shows the usual install dialog, with every scope. Nothing installs until the user allows it. If the plugin is already installed at that version, the link opens it in Settings, Plugins.

Publish a plugin

1. Create a publishing token

In Flare, open Settings, Plugins, Developer and choose New token. Name it for where it will be used, such as a laptop or a CI job. Copy it now: Flare shows it once and keeps only a hash. Afterwards you'll see its first few characters, so you can tell tokens apart. Revoke any token that leaks, on the same screen.

A token can publish your plugins and nothing else. It can't make tokens or read your account.

2. Sign in

npx flare-plugin login

Paste the token when asked, or pass it with --token. The CLI checks it with the store and keeps it in your user's config folder, readable only by you. flare-plugin whoami shows which account you're publishing as, and flare-plugin logout removes the token.

In CI, set FLARE_TOKEN instead. It's used before a kept token.

3. Publish

npx flare-plugin publish

publish validates and builds the plugin, packs it like flare-plugin pack, and uploads it. It prints the result: the version, whether it went live or is waiting for review, and every check.

  flare-plugin publish

  ● flare.orders (Orders 1.1.0): the manifest is valid, with 1 widget and 1 row action
  ● It asks for 2 scopes:
    data:read   Read the database you have open
    data:write  Change records in it
    A person will review this before it goes live, because it can change data.
  ● Built dist in 412ms plugin.js 7.9 kB, plugin.css 2.3 kB
  ● Sending flare.orders 1.1.0 to the store (https://api.flare.tools)

  ● flare.orders 1.1.0 is waiting for review.
    A person reviews it before it goes live, because it can change data.
    The decision and any note show in Flare: Settings, Plugins, Developer.

The first version you publish claims the plugin's id for your account. Later versions must come from the same account, each with a higher version. The store takes plain release versions, such as 1.2.0, with no pre-release tags.

The checks

Every version goes through automatic checks first:

Check	What it looks at	When it fails
The package	A safe archive under 10MB, with no links, no absolute paths and nothing outside its own folder.	Error
The manifest	Valid for the plugin API Flare has now, as flare-plugin validate checks it.	Error
The bundle	dist/plugin.js is present, for a plugin with code.	Error
Themes	Each theme's colours meet WCAG contrast. See Themes.	Warning
What the code does	Dynamic code (eval, new Function), remote script or style URLs, and very long single lines that suggest hidden code. A sandboxed plugin needs none.	Warning

An error fails the version, with the message, and nothing is listed. A warning sends the version to a reviewer, even if its scopes wouldn't. Information findings are shown and change nothing.

Run flare-plugin validate and flare-plugin build before you publish, and the first three checks won't surprise you.

Review

After the checks, what a version can do decides where it goes. reviewTier in @flare/plugin makes the same call:

A version that	Goes
Touches no data: adds themes, formats cells on screen or copies text, with no warnings	Live at once, after the checks.
Can read data (data:read), change it (data:write), reach the network (network:<host>), or got a warning	To a person at Flare, for review.

Anything that can see your data is reviewed by a person, not only what can change it or send it away. The reviewer sees the manifest, the scopes, what changed since the live version, the check results, the README and every file in the package. They approve the version or reject it with a note.

Approving puts the version live. Review usually takes a few days. If a reviewer approved the live version, the plugin's card shows Reviewed by Flare.

Where your versions stand

Settings, Plugins, Developer lists your plugins under My plugins, with every version you've sent, what the checks found and any note from a reviewer. publish prints the checks and the status as it sends a version.

Status	What it means	What to do
Live	In the store. Users can install it.	Nothing.
In review	Waiting for a person at Flare.	Wait. The decision shows in My plugins.
Rejected	A reviewer turned it down. Their note says why.	Fix it and publish a newer version.
Failed	A check found an error. The package wasn't kept.	Fix it and publish again. The same version works.

A rejected version number can't be sent again. A failed one can.

Get through review faster

Ask for as little as you can, and make what you can optional. Say in the README what the plugin sends where, and why. Reviewers read every file you ship, so keep dist/ readable: minified is fine, obfuscated is not.

Update a plugin

1. Raise version in package.json.
2. Run flare-plugin publish again from the same account.

Updates go through the same checks, and review when they need it.

Flare checks store plugins for updates when Settings, Plugins opens and once a day. The Updates tab lists what's newer, with any new scopes it asks for. Update shows the install dialog with only what's new in front of the user. If they allow it, the update installs and the plugin stays on. See What users see.

Share it by hand

Pack it

npm run pack

flare-plugin pack validates and builds, then writes <name>-<version>.tgz in the plugin's folder. The format matches npm pack, with every file under package/:

  flare-plugin pack

  ● flare.orders (Orders 1.0.0): the manifest is valid, with 1 widget and 1 command
  ● Built dist in 398ms plugin.js 6.1 kB, plugin.css 2.3 kB
  ● Packed flare-plugin-orders-1.0.0.tgz 5 files, 4.2 kB
    Install it in Flare from Settings, Plugins, Install from a file.

The archive holds package.json, dist/, the README, a licence and changelog if you have them, and the icon the manifest names. Your source files stay on your computer. Scoped names follow npm: @flare/orders at 1.0.0 becomes flare-orders-1.0.0.tgz.

As a file

Send the .tgz to whoever needs it. In Flare, they open Settings, Plugins, choose Install plugin, then From a file (.tgz). A .tgz from npm pack works too.

On npm

A plugin is already an npm package, so npm publish works:

npm run build
npm publish

In Flare, Install plugin, From npm takes the package name. Flare downloads it from the registry and checks its integrity before showing what it asks for.

Before you publish to npm, remove "private": true from package.json. npm create flare-plugin adds it so nothing gets published by mistake. Also make sure dist/ is built and included.

From a folder

For a plugin built on the same computer, Install plugin, From a folder installs it straight from its folder. Build dist/ first.

What Flare checks on install

However a plugin arrives, Flare checks it before showing the user anything:

• the package has a name, a version and a valid flare manifest, and each problem is reported with its location;
• the manifest's api range matches this version of Flare;
• the archive has no links, no absolute paths and nothing outside its own folder;
• a store download matches the integrity hash the store sent with it, and is the plugin and version asked for.

Then Flare shows the install dialog described in Scopes and permissions.