Manual

Install Dashfy

Add the Dashfy runtime packages:

pnpm add @dashfy/server @dashfy/ui

And the dev tooling used to run the server:

pnpm add -D tsx dotenv-cli concurrently

Create the Dashfy server

Add a dashfy.server.ts file at the project root. It loads your dashboard configuration and starts the Dashfy backend:

import { Dashfy } from '@dashfy/server'

const dashfy = new Dashfy()

await dashfy.configureFromFile('./dashfy.config.yml')

await dashfy.start()

Create the dashboard config

Add a dashfy.config.yml file at the project root. This is where you arrange dashboards and widgets:

port: 5001
apis:
  pollInterval: 300000
dashboards:
  - title: Dashfy Dashboard
    columns: 1
    rows: 1
    widgets:
      - extension: dashfy
        widget: Inspector
        x: 0
        y: 0
        columns: 1
        rows: 1

Render the dashboard

Render <Dashfy /> in your app. In src/App.tsx:

import { Dashfy } from '@dashfy/ui'

export const App = () => {
  return <Dashfy />
}

Import the styles and load the themes at your app entry (for example src/main.tsx):

import '@dashfy/ui/styles.css'

import { ThemeRegistry } from '@dashfy/ui'
import * as React from 'react'
import { createRoot } from 'react-dom/client'

import { App } from './App'

ThemeRegistry.loadAllThemes()

createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
)

Make the config endpoint reachable

The UI reads its configuration from /config. In development, proxy /config to the Dashfy server (http://localhost:5001) using whatever your dev server provides. With Vite, that's server.proxy in vite.config.ts:

import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [react()],
  server: {
    port: 3000,
    proxy: {
      '/config': 'http://localhost:5001',
    },
  },
})

For other setups, use the equivalent mechanism: Next.js uses rewrites in next.config.ts, and Astro and React Router proxy through their underlying Vite config. See the Next.js, Astro, and React Router guides for concrete examples.

Add scripts and environment

Add the dev scripts to package.json so the app and server run together, and create a .env file for extension secrets. Replace dev with your app's own dev command if it isn't Vite:

{
  "scripts": {
    "dev": "vite",
    "dev:server": "dotenv -e .env -- tsx watch dashfy.server.ts",
    "dev:all": "concurrently \"pnpm dev:server\" \"pnpm dev\""
  }
}

Add dashfy.json

Add a dashfy.json at the project root so the CLI knows where to apply changes when you run dashfy add. Point paths.app at your actual app file — it's the file dashfy add edits to register widgets (default src/App.tsx):

{
  "$schema": "https://dashfy.dev/schema.json",
  "registries": {},
  "paths": {
    "app": "src/App.tsx",
    "server": "dashfy.server.ts",
    "config": "dashfy.config.yml",
    "env": ".env"
  }
}

Start developing

Run everything together and open http://localhost:3000:

pnpm run dev:all