Plugins & Extensions

Coming Soon

The Plugin System is currently in active development. The specifications below are provisional and subject to change.

Dataface is designed to be extensible. You can add custom chart types, variable inputs, data adapters, and more through the plugin system.

---

Using Plugins

To use a plugin in your dashboard, you must first declare it in your dashboard's extensions section.

extensions:
  - id: dataface-plugin-funnel
    version: "1.0.0"
    source: pypi  # or npm, github, local

Once declared, you can use the plugin's features (charts, inputs, etc.) using the custom: prefix.

Custom Charts

Use a plugin-provided chart type in your charts definition:

charts:
  my_funnel:
    title: "Conversion Funnel"
    query: queries.conversions
    type: custom:conversion_funnel  # Provided by plugin
    steps: [signup, activation, purchase]

Custom Inputs

Use a plugin-provided input type for variables:

variables:
  fiscal_q:
    input: custom:fiscal_picker     # Provided by plugin
    options:
      start_month: 4

Custom Adapters

Query data from non-standard sources (like APIs) using custom adapters:

queries:
  stripe:
    adapter: stripe                 # Provided by plugin
    metrics: [mrr]

---

Developing Plugins

Dataface plugins are Python packages (backend) and/or NPM packages (frontend) that export specific extension points.

Extension Points

1. Charts: New visualization types (React/Vega-Lite).
2. Variables: Custom input controls (React).
3. Adapters: Custom data sources (Python).
4. Actions: Server-side behaviors (Python).
5. Transforms: Data processing logic (Python).

Creating a Plugin

A typical plugin structure:

my-plugin/
  pyproject.toml        # Python metadata & entry points
  package.json          # Frontend metadata (if applicable)
  src/
    __init__.py         # Python logic
    index.tsx           # React components

1. Python Extensions (Backend)

Define extensions in Python by subclassing the base classes from dataface.extensions.

Example: Custom Data Adapter

from dataface.extensions import AdapterExtension

class StripeAdapter(AdapterExtension):
    adapter_name = "stripe"

    async def execute_query(self, query, variables):
        # Fetch data from Stripe API
        return [...]

def register_extension():
    return StripeAdapter()

Register it in pyproject.toml:

[project.entry-points."dataface.adapters"]
stripe = "my_plugin:register_extension"

2. React Extensions (Frontend)

Define frontend components (charts, inputs) using the Dataface Runtime API.

Example: Custom Chart

import { DatafaceComponent } from '@dataface/runtime';
import { FunnelChart } from './FunnelChart';

export const funnelPlugin: DatafaceComponent = {
  type: 'custom:funnel',
  schema: zodSchema,
  render: ({ chart, data }) => <FunnelChart data={data} />
};

---

Plugin Registry

(Coming Soon)

The official Dataface Plugin Registry will allow you to discover and install community plugins directly.

For now, install plugins via pip (for Python logic) or npm (for frontend components).

pip install dataface-plugin-stripe
npm install @dataface/plugin-funnel