Debugging

Plugin code runs in frames inside Flare, not in a browser tab you can inspect. Flare collects the logs and errors for you. In development they print in your terminal. Errors also show on the view that broke, and everything lands in the plugin's log in Flare.

Logs in the terminal

While flare-plugin dev runs, everything your frames write to console and everything you pass to ctx.log prints in the terminal. Each line has the time and the frame it came from:

  ● 14:02:11 Flare loaded the plugin.
  14:02:12 logic Counted orders: 12842
  14:02:14 widget count warn The table has no created_at field
  14:02:30 widget per-day crashed Cannot read properties of undefined (reading 'value')
      at setup (src/widgets/PerDay.vue:21:18)

logic is the hidden frame that runs setup, cell formatters, columns, actions, commands and function result views. View frames are labelled by kind and id, such as widget count, commandView lookup or transform chart.

console.info, console.warn and console.error are coloured by level. They still print in the frame's own console too.

definePlugin({
  setup(ctx) {
    ctx.log('Started on', ctx.target?.engine ?? 'no database');
  },
});

Errors on the view

When a view throws, Flare replaces it with the error. From a dev server you get the full stack and a Dismiss button, right on the widget you were looking at:

  This widget stopped with an error
  Cannot read properties of undefined (reading 'value')
  at setup (src/widgets/PerDay.vue:21:18)
  ...

An installed plugin shows only the message and points to the plugin's log. Uncaught errors and rejected promises in either kind of frame are reported to Flare as crashes and logged the same way.

Errors from ctx

When Flare refuses or can't complete a call, it rejects with a PluginError. Its code says why. Catch the codes you expect:

definePlugin({
  commands: {
    lookup: async (_, ctx) => {
      try {
        const response = await ctx.fetch('https://api.example.com/status');
        return { message: `Status ${response.status}` };
      } catch (error) {
        if (error instanceof PluginError && error.code === 'HOST_NOT_ALLOWED') {
          return {
            message: 'Add api.example.com to permissions.network',
            tone: 'warning',
          };
        }
        throw error;
      }
    },
  },
});

The codes are listed in the ctx reference.

If one of your functions throws, the error goes back to Flare the same way. Flare shows it where the user triggered it, such as a row action's toast, and writes it to the plugin's log.

The plugin's log

Every plugin has a log on its card in Settings, Plugins. It holds what the plugin wrote with ctx.log and console, its crashes, and problems Flare found, such as a contribution that's declared but not implemented. Check it first when an installed plugin misbehaves on someone else's computer.

When nothing shows up

If the plugin isn't in Settings, Plugins, check that Developer mode is on. Then check that flare-plugin dev is running on 5199 or on a port you added. The terminal prints the port.

If a contribution is missing, its engines may leave out the open database. Or it may be declared but not implemented. The terminal lists those when Flare loads the plugin.

If package.json has a problem, the dev server prints it on save with its location, such as flare.contributes.widgets.0.id.

If a cell formatter does nothing, check its match. A cell must match every selector you give, so fields and types together match fewer cells than either alone.