Astro

Create a new app

Scaffold the minimal Astro starter. You will be prompted to choose extensions, which Dashfy sets up for you:

pnpm dlx dashfy@latest init -t astro-starter

Prefer the full, pre-configured demo? Use the astro-app template instead:

pnpm dlx dashfy@latest init -t astro-app

Install dependencies

If you scaffolded with --no-install, install dependencies inside the new project directory (cd my-dashfy-app):

pnpm install

Start developing

Run the Astro app and the Dashfy server together:

pnpm run dev:all

Open http://localhost:3000 to see your dashboard. The Dashfy server runs on http://localhost:5001.

Install Dashfy

Add the Astro React integration:

pnpm dlx astro add react

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

Create the Dashfy app component

Create src/components/DashfyApp.tsx:

import '@dashfy/ui/styles.css'

import { Dashfy, ThemeRegistry } from '@dashfy/ui'

ThemeRegistry.loadAllThemes()

export default function DashfyApp() {
  return <Dashfy />
}

Render it as a client-only island. In src/pages/index.astro, use the client:only="react" directive so it renders in the browser:

---
import Layout from '@/layouts/main.astro'
import DashfyApp from '@/components/DashfyApp'
---

<Layout>
  <DashfyApp client:only="react" />
</Layout>

Proxy the config endpoint

The UI reads its configuration from /config. Set the port and proxy it to the Dashfy server in astro.config.mjs:

// @ts-check
import react from '@astrojs/react'
import { defineConfig } from 'astro/config'

// https://astro.build/config
export default defineConfig({
  server: { port: 3000 },
  integrations: [react()],
  vite: {
    server: {
      proxy: {
        '/config': 'http://localhost:5001',
      },
    },
  },
})

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:

{
  "scripts": {
    "dev": "astro 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": "src/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:all