definePlugin

A plugin's src/index.ts default exports the result of definePlugin. It implements each contribution in the manifest under the same id.

import { definePlugin } from '@flare/plugin';

export default definePlugin({
  setup: (ctx) => ctx.log('Ready on', ctx.target?.name ?? 'no database'),
  widgets: { revenue: Revenue },
  cells: {
    customer: ({ value }) => ({ text: String(value), icon: 'credit-card', mono: true }),
  },
  columns: { total: (rows) => rows.map(({ values }) => Number(values.total ?? 0)) },
  rowActions: {
    open: ({ records }, ctx) => ctx.openUrl(`https://example.com/${records[0]!.id}`),
  },
  commands: {
    lookup: async ({ arguments: args }) => ({ props: { email: args.email } }),
  },
  commandViews: { lookup: Lookup },
  transforms: { chart: Chart },
});

definePlugin returns its argument unchanged. It exists for the types.

Functions run in the plugin's hidden logic frame, not in Flare's window. Calls and results travel as messages, so return plain data that structuredClone can copy. Vue reactive objects are unwrapped for you. Components mount in their own view frames.

PluginDefinition

Key	Type	Implements
setup	(ctx) => void | Promise<void>	Runs once when the plugin starts, before anything else. Preferences are already available.
widgets	Record<id, ViewComponent>	contributes.widgets
cells	Record<id, CellFormatter>	contributes.cells
columns	Record<id, ComputedColumn>	contributes.columns
rowActions	Record<id, RowAction>	contributes.rowActions
commands	Record<id, Command>	contributes.commands
transforms	Record<id, ViewComponent | ResultTransform>	contributes.transforms: a component with view, a function without
commandViews	Record<id, ViewComponent>	The views of contributes.commands declared with view

ViewComponent is any component from a .vue file or defineComponent. Vue functional components are excluded, because they're plain functions. That way any function in transforms is typed as a ResultTransform.

Flare only shows contributions the manifest declares, and only calls ones the code implements. flare-plugin dev and validate report both kinds of mismatch.

CellFormatter

type CellFormatter = (cell: Cell) => CellDisplay | null;

Formats the cells its manifest entry matches. Flare calls it for many cells at once as a table draws, so keep it fast. It gets no ctx and can't read data. Return null to leave a cell alone.

Cell

Field	Type	What it is
value	unknown	The value.
field	string	The field or column it is in.
type	ValueType	The kind of value, named the same on every engine.
columnType	string or null	The column type the database declares, or null if it declares none.
record	DataRecord	The whole record.
container	string	The container it is in.

CellDisplay

Field	Type	What it is
text	string	The text shown. Required.
tone	Tone	neutral, positive, warning, danger or info.
icon	string	A Lucide icon name in kebab case, shown before the text.
title	string	Hover text.
href	string	An https link, opened in the browser.
mono	boolean	Sets the text in monospace, for ids, hashes and codes.

Flare draws it in the grid's own style. There's no way to return HTML.

ComputedColumn

type ComputedColumn = (
  rows: DataRecord[],
  context: { container: string },
  ctx: PluginContext
) => Promise<(unknown | CellDisplay)[]> | (unknown | CellDisplay)[];

A column computed from each row. Flare calls it with a page of rows at a time, so you can fetch once per page. Return one value per row, in order. Each is either a plain value, which Flare formats as usual, or a CellDisplay.

RowAction

type RowAction = (
  input: { records: DataRecord[]; container: string },
  ctx: PluginContext
) => Promise<ActionResult | void> | ActionResult | void;

type ActionResult = { message?: string; tone?: Tone };

An action on records, from a row's menu or a selection. Writes go through ctx.data, so Flare asks first on production and Activity records them. Return a message to show one.

Command

type Command = (
  input: { arguments: Record<string, unknown> },
  ctx: PluginContext
) => Promise<ActionResult | CommandView | void> | ActionResult | CommandView | void;

type CommandView = { props: Record<string, unknown> };

A command from the palette. It gets the arguments the user filled in, by name. A command declared with view returns { props }, and Flare opens its component from commandViews with them. Without view, it can return a message.

ResultTransform

type ResultTransform = (
  result: QueryResult & { language: string },
  ctx: PluginContext
) => Promise<QueryResult> | QueryResult;

Turns a query's results into new rows for Flare to show, such as a summary, a pivot or a flattened copy. The original results don't change. A function written inline in transforms gets this type automatically.

The data types

Type	Shape
DataRecord	{ id: string; path: string; values: Record<string, unknown> }
Container	{ path: string; name: string; kind: 'collection' | 'table' | 'view' | 'keyspace' }
QueryResult	{ columns: string[]; rows: unknown[][]; truncated: boolean }
Tone	'neutral' | 'positive' | 'warning' | 'danger' | 'info'

These and every other type on this page are exported from @flare/plugin.