Flare Docs | Build plugins for Flare

1 A widget: a Vue component that counts through Flare

src/widgets/Count.vue

vue

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

// What the person picked in the widget's settings.
const { settings
 } = useWidget
<{ container
?: string }>();

// Counts through Flare, and 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": "acme.row-count",
    "title": "Row count",
    "description": "How many rows a table holds.",
    "author": "Acme",
    "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 into Flare. One manifest to declare them.

Every contribution works on every database Flare opens, from Firestore to Redis, unless it says otherwise.

Dashboard widgets

A Vue component on the dashboard's grid, with settings Flare draws and data that refreshes with it.

ts

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

Read the guide

Cell formatters

How matching cells look in every table: words, a tone, an icon, a link. Plain data, never HTML.

ts

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

Read the guide

Computed columns

A column worked out from each row, a page of rows at a time, so one fetch serves the page.

ts

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

Read the guide

Row and bulk actions

In a row's menu and on a selection. Writes go through Flare, confirmed 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, with arguments Flare asks for and an optional view of the answer.

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

Another tab beside Table and JSON in the Query Editor: a component, or a function that reshapes rows.

ts

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

definePlugin
({ transforms
: { count
 } });

Read the guide

And colour themes

A theme is data, not code: thirty colours by role, which Flare spreads over every screen, chart and value chip. A plugin can be nothing but themes, and needs no permission for them.

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

Safe by design. A plugin asks. Flare decides.

Flare holds the keys to production, so a plugin never touches them. It runs in a sandbox of its own, with no Node, no file system and no network, and it never sees a password or a token. It reaches your data only by asking Flare, which checks the scopes you allowed, keeps it off production until you turn that on, and then acts as you would: every change is confirmed on production, held to your team's roles, and written to Activity under the plugin's name, with undo where Flare can undo it.

A sandbox of its own

Frames on the plugin's own origin, under a strict content security policy. The only way out is ctx.fetch, to hosts it declared.

Never a password

A plugin knows which database is open and whether it is production. Never where it is, or how to sign in to it.

Every write on the record

Changes go through Flare's own guarded write: confirmed on production, allowed by the team's roles, and in Activity.

Quickstart

A widget in Flare. In three steps.

1

Make a plugin

It asks for a name and what to start with, and writes a plugin with 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

A dev server on port 5199, with Vue hot reload and the plugin's logs in your terminal.

bash

cd row-count
npm install
npm run dev

3

Turn on Developer mode

In Flare, open Settings, Plugins and turn on Developer mode. Your plugin appears there, marked Development, and its widget is in Add widget on the dashboard.

Plugins