Scaffold a Dashfy dashboard with Next.js, or add Dashfy to an existing Next.js app.
Dashfy runs as two processes: the Next.js app that renders the client-only dashboard UI, and a separate Dashfy Node server that streams data over Socket.IO.
Scaffold a ready-to-run Next.js project from the terminal.
Add Dashfy manually to an app you already created.
Use the CLI
Create a new app
Scaffold the minimal Next.js starter. You will be prompted to choose extensions, which Dashfy sets up for you:
pnpm dlx dashfy@latest init -t next-starterPrefer the full, pre-configured demo? Use the
next-app template instead:
pnpm dlx dashfy@latest init -t next-appInstall dependencies
If you scaffolded with --no-install, install dependencies inside the new project
directory (cd my-dashfy-app):
pnpm installStart developing
Run the Next.js app and the Dashfy server together:
pnpm run dev:allOpen http://localhost:3000 to see your dashboard. The Dashfy server runs on http://localhost:5001.
Existing project
Install Dashfy
Add the Dashfy runtime packages:
pnpm add @dashfy/server @dashfy/uiAnd the dev tooling used to run the server:
pnpm add -D tsx dotenv-cli concurrentlyCreate 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: 1Create the Dashfy app component
The dashboard UI is client-only. Create components/DashfyApp.tsx:
'use client'
import '@dashfy/ui/styles.css'
import { Dashfy, ThemeRegistry } from '@dashfy/ui'
ThemeRegistry.loadAllThemes()
export default function DashfyApp() {
return <Dashfy />
}Render it client-side
Load the component with next/dynamic and ssr: false so it never renders on the
server. For example, in app/page.tsx:
'use client'
import dynamic from 'next/dynamic'
const DashfyApp = dynamic(() => import('@/components/DashfyApp'), {
ssr: false,
})
export default function Page() {
return <DashfyApp />
}Proxy the config endpoint
The UI reads its configuration from /config. Proxy it to the Dashfy server in
next.config.ts:
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
async rewrites() {
return [
{ source: '/config', destination: 'http://localhost:5001/config' },
{
source: '/config/:path*',
destination: 'http://localhost:5001/config/:path*',
},
]
},
}
export default nextConfigAdd 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:
{
"scripts": {
"dev": "next dev",
"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:
{
"$schema": "https://dashfy.dev/schema.json",
"registries": {},
"paths": {
"app": "components/DashfyApp.tsx",
"server": "dashfy.server.ts",
"config": "dashfy.config.yml",
"env": ".env"
}
}Start developing
Run everything together and open http://localhost:3000:
pnpm run dev:allAdd extensions
With dashfy.json in place, add extensions (widgets + data sources) from the
registry. The CLI installs the package and sets it up in components/DashfyApp.tsx,
dashfy.server.ts, dashfy.config.yml, and .env:
pnpm dlx dashfy@latest add @dashfy/githubSee Extensions and the CLI reference for details.