Getting started

A Flare plugin is an npm package. Its package.json holds a manifest that declares what the plugin adds and what it may do. Its src/index.ts implements that in TypeScript, with Vue components for anything it draws.

You need Node 20.12 or later, and Flare on the same computer.

Make a plugin

npm

npm create flare-plugin@latest

pnpm

pnpm create flare-plugin

bun

bun create flare-plugin

It asks four questions:

1. The plugin's name, as people see it in Flare.
2. Its id, such as flare.row-count. The default comes from the name and the author. The id is also the plugin's origin in Flare, which holds its storage, so pick one you'll keep.
3. Who makes it.
4. What to start with: a dashboard widget, a cell formatter, a row action, a command, a result view or a colour theme. The defaults are a widget, a cell formatter and a command.

Every question has a flag. Add --yes to accept the defaults for anything you leave out:

npm create flare-plugin@latest -- --title "Row count" --id flare.row-count \
  --author Flare --starters widget,cell --yes

See the CLI reference for every flag.

What you get

row-count/
  package.json        the manifest, in "flare", and a script for each command
  src/index.ts        export default definePlugin({ ... })
  src/widgets/        a widget, if you picked one
  src/views/          a command's view and a result view, if you picked them
  tsconfig.json       TypeScript, set up for Vue
  env.d.ts
  README.md

The manifest is the flare field in package.json. It lists each contribution by id, and the permissions the plugin asks for. src/index.ts implements each contribution under the same id:

import { definePlugin } from '@flare/plugin';
import Count from './widgets/Count.vue';

export default definePlugin({
  widgets: {
    count: Count,
  },
  cells: {
    /** Called for many cells as a table draws: keep it quick. Null leaves a cell as it is. */
    links: ({ value }) => {
      if (typeof value !== 'string' || !value.startsWith('https://')) return null;
      const url = new URL(value);
      return { text: url.host + url.pathname, href: url.href, icon: 'external-link' };
    },
  },
});

Hover any name to see its type. Your editor gets the same types from @flare/plugin.

Run it in Flare

Install the dependencies and start the dev server:

cd row-count
npm install
npm run dev

npm run dev runs flare-plugin dev, a Vite dev server on port 5199:

  flare-plugin dev

  ● Serving flare.row-count (Row count 0.1.0) on http://localhost:5199
    Turn on Developer mode in Flare, Settings, Plugins, Developer, and it shows up there.
    Components reload in place as you save. Logs and errors from the plugin appear here.

Then, in Flare:

1. Open Settings, then Plugins, then Developer.
2. Turn on Developer mode. Flare checks port 5199 for a dev server every two seconds.
3. Your plugin appears under Installed, marked Development. The terminal prints Flare loaded the plugin.

Open a database's dashboard and choose Add widget. Your widget is listed under the plugin's name. Edit src/widgets/Count.vue and it updates in place without losing its state.

Two plugins at once

Give each dev server its own port with flare-plugin dev --port 5200. Then add that port in Settings, Plugins, Developer.

A plugin from a dev server only runs on your computer, while Developer mode is on and the server is up. It replaces any installed plugin with the same id. To give it to other people, see Publishing.

Next

• Your first widget: settings, reading data, and Flare's components.
• Scopes and permissions: what a plugin can ask for, and what users see.
• The dev loop: hot reload, checks and every command.