Flare Docs | Build plugins for Flare

1 A widget: a Vue component that counts through Flare

src/widgets/Count.vue

vue

<script lang="ts" setup>
import { Stat
, useAggregate
, useWidget
 } from '@flare/plugin/vue';

// The widget's settings, as the user filled them in.
const { settings
 } = useWidget
<{ container
?: string }>();

// Flare runs the count, and runs it again when the
// setting changes or the dashboard refreshes.
const { data
, loading
 } = useAggregate
(() =>
  settings
.value
.container

    ? { container
: settings
.value
.container
, aggregate
: 'count' }
    : null
);
</script>

<template>
  <Stat

    :
value
="data
"
    :
label
="`in ${settings
.container
}`"
    :
loading
="loading
"
  />
</template>

src/index.ts

ts

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

export default definePlugin
({
  widgets
: { count
: Count
 },
});

2 The manifest: what it adds, and what it may do

package.json

json

{
  "name": "flare-plugin-row-count",
  "version": "1.0.0",
  "flare": {
    "id": "flare.row-count",
    "title": "Row count",
    "description": "How many rows a table holds.",
    "author": "Flare",
    "permissions": { "data": "read" },
    "contributes": {
      "widgets": [
        {
          "id": "count",
          "title": "Row count",
          "size": { "w": 4, "h": 3 },
          "settings": [
            {
              "name": "container",
              "title": "Table or collection",
              "type": "container",
              "required": true
            }
          ]
        }
      ]
    }
  }
}

Hover the code: the types are the real ones from @flare/plugin.

What plugins add

Six ways to extend Flare. Plus themes.

Declare them in one manifest. Each one works on every database Flare opens, from Firestore to Redis, unless you limit it.

Dashboard widgets

A Vue component on the dashboard. Flare draws its settings form and refreshes its data.

ts

const { data
 } = useRead
(() => ({
  container
: 'orders',
  orderBy
: [
    { field
: 'created_at', direction
: 'desc' },
  ],
  limit
: 10,
}));

Read the guide

Cell formatters

Change how matching cells look in every table. Return text, a tone, an icon or a link.

ts

definePlugin
({
  cells
: {
    status
: ({ value
 }) => ({
      text
: String
(value
),
      tone
: value
 === 'paid'
        ? 'positive'
        : 'warning',
    }),
  },
});

Read the guide

Computed columns

A column computed from each row. You get a page of rows per call, so one fetch covers the page.

ts

definePlugin
({
  columns
: {
    total
: (rows
) =>
      rows
.map
(({ values
 }) =>
        Number
(values
.price
) *
        Number
(values
.quantity
)
      ),
  },
});

Read the guide

Row and bulk actions

Actions in a row's menu and on a selection. Writes go through Flare, which asks first on production.

ts

definePlugin
({
  rowActions
: {
    archive
: async ({ records
, container
 }, ctx
) => {
      for (const { id
 } of records
) {
        await ctx
.data
.update
(container
, id
, {
          archived
: true,
        });
      }
    },
  },
});

Read the guide

Commands

Entries in the command palette. Flare asks for the arguments, and you can answer with a view.

ts

definePlugin
({
  commands
: {
    lookup
: async ({ arguments
: args
 }, ctx
) => {
      const email
 = String
(args
.email
);
      const found
 = await ctx
.data
.read
({
        container
: 'customers',
        filters
: [
          { field
: 'email', operator
: '==', value
: email
 },
        ],
      });
      return { props
: { found
 } };
    },
  },
});

Read the guide

Result views

A tab beside Table and JSON in the Query Editor. Draw the results with a component, or reshape them with a function.

ts

const count
: ResultTransform
 = (result
) => ({
  columns
: ['rows'],
  rows
: [[result
.rows
.length
]],
  truncated
: false,
});

definePlugin
({ transforms
: { count
 } });

Read the guide

Colour themes

A theme is thirty colours in your manifest, one for each role. Flare applies them to every screen, chart and value chip. Themes need no code and no permissions.

Make a theme

jsonc

{
  "id": "harbour",
  "title": "Harbour",
  "mode": "dark",
  "colors": {
    "canvas": "#0b1016",
    "panel": "#111821",
    "accent": "#7cc4fa",
    "chart": "#5aa7e8"
    // and the other roles, with a colour for each kind of value
  }
}

Security

Sandboxed. Flare checks every call.

A plugin runs in its own sandbox with no Node, no file system and no network. It never sees a password or a token. To read or change data, it asks Flare, and Flare checks the scopes you allowed. Plugins stay off production databases until you turn that on. How permissions work

Its own origin

Plugin code runs in frames on the plugin's own origin, under a strict content security policy. ctx.fetch reaches only the hosts it declared.

No credentials

A plugin knows which database is open and whether it's production. It never learns where the database lives or how to sign in.

Every write logged

Writes go through Flare's guarded write. Production asks first, team roles apply, and Activity records the change.

Quickstart

Your first plugin. Three steps.

1

Make a plugin

Answer a few questions. The defaults give you a widget, a cell formatter and a command.

npmpnpmbun

bash

npm create flare-plugin@latest

bash

pnpm create flare-plugin

bash

bun create flare-plugin

2

Serve it

This starts a dev server on port 5199. Components hot reload, and your plugin's logs print here.

bash

cd row-count
npm install
npm run dev

3

Turn on Developer mode

In Flare, open Settings, Plugins, Developer and turn on Developer mode. Your plugin shows up marked Development, and its widget is under Add widget on the dashboard.

Plugins