# CLI (/docs/cli)

The `dashfy` CLI helps you create a new Dashfy project and add extensions (widgets +
data sources) to an existing one.

Scaffold a project:

```npm
npx dashfy@latest init
```

Add an extension:

```npm
npx dashfy@latest add @getdashfy/github
```

## Addresses

You reference extensions by **address**:

| Address                          | Resolves to                                              |
| -------------------------------- | -------------------------------------------------------- |
| `github`                         | the `@getdashfy` namespace (default) → `…/r/github.json` |
| `@getdashfy/github`              | the `@getdashfy` namespace explicitly                    |
| `@acme/widget`                   | a custom namespace declared in `dashfy.json`             |
| `https://example.com/r/foo.json` | a direct URL                                             |
| `./local/foo.json`               | a local registry file                                    |
| `owner/repo/foo`                 | a registry item in a GitHub repo (`#ref` optional)       |

## `dashfy init|create [name]`

Scaffolds a runnable Dashfy app (a framework client + Node server + configuration).
`create` is an alias for `init`.

| Flag                        | Description                                                                                                                                                                  |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-t, --template <template>` | `vite-starter` (default), `vite-app`, `astro-starter`, `astro-app`, `next-starter`, `next-app`, `react-router-starter`, `react-router-app`, `start-starter`, or `start-app`. |
| `-e, --extensions <names>`  | Comma-separated extensions to set up (`*-starter` only).                                                                                                                     |
| `-c, --cwd <cwd>`           | Working directory.                                                                                                                                                           |
| `--no-install`              | Skip installing npm dependencies.                                                                                                                                            |
| `-y, --yes`                 | Accept defaults / skip prompts.                                                                                                                                              |

```npm
npx dashfy@latest init my-app -t vite-app
```

## `dashfy add [extensions...]`

Resolves the extension address(es), installs the `@getdashfy/ext-*` package(s), and
sets them up automatically (widgets in `App.tsx`, server API in your bootstrap,
`.env` entries, and a starter block in `dashfy.config.yml`). With no arguments, `add`
prompts you to pick from the catalog. See [Extensions](/docs/extensions).

| Flag              | Description                                         |
| ----------------- | --------------------------------------------------- |
| `-c, --cwd <cwd>` | Working directory.                                  |
| `--no-install`    | Skip installing npm dependencies (set up only).     |
| `--dry-run`       | Print what would be added without writing anything. |
| `-y, --yes`       | Accept defaults / skip prompts.                     |

## `dashfy remove [extensions...]`

Reverses what `add` set up. Removal is registry-first and idempotent, and it
falls back to deriving the setup from your project when the registry is unreachable.

| Flag              | Description                                            |
| ----------------- | ------------------------------------------------------ |
| `-c, --cwd <cwd>` | Working directory.                                     |
| `--keep-deps`     | Leave npm dependencies installed (setup-only removal). |
| `--dry-run`       | Print what would be removed without writing anything.  |
| `-y, --yes`       | Skip the confirmation prompt.                          |

## `dashfy search [registries...]`

Searches extension catalogs and prints matches (aliased as `dashfy list`). Queries
are fuzzy-matched and ranked across name, title, description, and categories, and
each result includes a ready-to-run add command.

Search for extensions:

```npm
npx dashfy@latest search --query git
```

Machine-readable report for CI:

```npm
npx dashfy@latest search @getdashfy --json
```

| Flag                  | Description                                                   |
| --------------------- | ------------------------------------------------------------- |
| `[registries...]`     | Registry namespace(s) to search (defaults to all configured). |
| `-q, --query <query>` | Filter by name, title, description, or category.              |
| `-t, --type <type>`   | Filter by item type (e.g. `registry:extension`).              |
| `-l, --limit <n>`     | Max items per registry (default `100`).                       |
| `-o, --offset <n>`    | Items to skip (default `0`).                                  |
| `--json`              | Output as JSON.                                               |

## `dashfy view <items...>`

Resolves the given address(es) and prints the full registry item JSON (deps, env
vars, widgets, starter config) — useful for inspection and piping:

```npm
npx dashfy@latest view @getdashfy/github | jq '.dependencies'
```

## `dashfy docs <extensions...>`

Resolves the extension(s) and prints setup-oriented documentation: setup notes,
required env vars, how it integrates into your app and server, the starter dashboard
it seeds, and a ready-to-run install command.

View documentation for an extension:

```npm
dashfy docs github
```

Machine-readable report for CI:

```npm
dashfy docs @getdashfy/github --json
```

## `dashfy info`

Prints a snapshot of the current project: detected files, `dashfy.json` paths,
configured registries, installed `ext-*` packages, and useful links.

```npm
npx dashfy@latest info --json
```

## `dashfy doctor [extensions...]`

Diagnoses the project and verifies each extension is fully set up. Exits non-zero
when any check fails, making it suitable as a CI gate. Falls back to inspecting
source files when the registry is unreachable.

Auto-detect installed extensions:

```npm
npx dashfy@latest doctor
```

Machine-readable report for CI:

```npm
npx dashfy@latest doctor @getdashfy/github --json
```

## Global flags

These apply to every command:

* `--json` — emit machine-readable JSON only and suppress human output. Place before
  the command (e.g. `dashfy --json add @getdashfy/github`); `info`, `search`, `view`,
  `docs`, and `doctor` also accept it after the command.
* `--silent` — mute non-error output.

## Project configuration (`dashfy.json`)

`dashfy init` writes a `dashfy.json`, and `add` reads it. It declares where the CLI
applies changes and any custom registries:

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

* `registries` are merged over the built-in `@getdashfy` namespace. A registry endpoint
  is a URL template containing `{name}`, or an object with `url` plus optional
  `params` / `headers` (values may reference `${ENV_VAR}` for auth).
* `paths` take precedence over the CLI's heuristic file discovery.

## Environment variables

`init`, `add`, and `registry add` load `.env` files before resolving registries (so
`${ENV_VAR}` auth works), in this precedence order — first match wins, existing
process env is never overridden:

```
.env.local
.env.development.local
.env.development
.env
```

CLI behavior can also be tuned with:

* `DASHFY_REGISTRY_URL` — base URL/dir for `@getdashfy` items (offline/dev).
* `DASHFY_REGISTRIES_URL` — location of the discovery index (`registries.json`).
* `DASHFY_TEMPLATE_DIR` / `DASHFY_GITHUB_URL` — template source for `init`.

## More

* [Registry](/docs/registry) — `registry add/remove/build/validate` and authoring.
* [MCP server](/docs/mcp) — `dashfy mcp` for AI assistants.


# Configuration (/docs/configuration)

Dashfy dashboards are defined using declarative configuration. You can author them as
a **TypeScript** object, **JSON**, or **YAML** — pick whichever fits your workflow.

A configuration declares one or more `dashboards`, each with a grid (`columns` ×
`rows`) and a list of `widgets` placed on that grid.

## Dashboard fields

| Field     | Type       | Description                      |
| --------- | ---------- | -------------------------------- |
| `title`   | `string`   | Display title for the dashboard. |
| `columns` | `number`   | Number of grid columns.          |
| `rows`    | `number`   | Number of grid rows.             |
| `widgets` | `Widget[]` | Widgets placed on the grid.      |

## Widget fields

Every widget references an `extension` and a `widget` name, and is positioned on the
grid. Remaining fields are widget-specific props.

| Field       | Type     | Description                                       |
| ----------- | -------- | ------------------------------------------------- |
| `extension` | `string` | Extension the widget comes from (e.g. `github`).  |
| `widget`    | `string` | Widget name exported by the extension.            |
| `x`         | `number` | Column position (0-based).                        |
| `y`         | `number` | Row position (0-based).                           |
| `columns`   | `number` | How many columns the widget spans.                |
| `rows`      | `number` | How many rows the widget spans.                   |
| *…props*    | `any`    | Widget-specific props (e.g. `repository`, `url`). |

> **Keep widgets inside the grid**
>
> A widget's `x + columns` must not exceed the dashboard's `columns`, and `y + rows` must not exceed
> its `rows`. Widgets should not overlap.

## TypeScript

```ts lineNumbers title="dashfy.config.ts"
import type { DashfyConfig } from '@getdashfy/types'

export const dashfyConfig: DashfyConfig = {
  dashboards: [
    {
      title: 'GitHub Dashboard',
      columns: 3,
      rows: 2,
      widgets: [
        {
          extension: 'github',
          widget: 'RepoBadge',
          x: 0,
          y: 0,
          columns: 1,
          rows: 1,
          repository: 'react/react',
        },
        {
          extension: 'github',
          widget: 'PullRequests',
          x: 1,
          y: 0,
          columns: 2,
          rows: 1,
          repository: 'vercel/next.js',
          state: 'open',
        },
        {
          extension: 'json',
          widget: 'JsonStatus',
          x: 0,
          y: 1,
          columns: 3,
          rows: 1,
          title: 'API Status',
          url: 'https://api.example.com/health',
          statuses: [
            {
              assert: 'equals(status, ok)',
              status: 'success',
              label: 'API Online',
            },
          ],
        },
      ],
    },
  ],
}
```

## JSON

```json lineNumbers title="dashfy.config.json"
{
  "dashboards": [
    {
      "title": "GitHub Dashboard",
      "columns": 3,
      "rows": 2,
      "widgets": [
        {
          "extension": "github",
          "widget": "RepoBadge",
          "x": 0,
          "y": 0,
          "columns": 1,
          "rows": 1,
          "repository": "react/react"
        },
        {
          "extension": "github",
          "widget": "PullRequests",
          "x": 1,
          "y": 0,
          "columns": 2,
          "rows": 1,
          "repository": "vercel/next.js",
          "state": "open"
        },
        {
          "extension": "json",
          "widget": "JsonStatus",
          "x": 0,
          "y": 1,
          "columns": 3,
          "rows": 1,
          "title": "API Status",
          "url": "https://api.example.com/health",
          "statuses": [
            {
              "assert": "equals(status, ok)",
              "status": "success",
              "label": "API Online"
            }
          ]
        }
      ]
    }
  ]
}
```

## YAML

```yml lineNumbers title="dashfy.config.yml"
title: GitHub Dashboard
columns: 3
rows: 2
widgets:
  - extension: github
    widget: RepoBadge
    x: 0
    y: 0
    columns: 1
    rows: 1
    repository: react/react
  - extension: github
    widget: PullRequests
    x: 1
    y: 0
    columns: 2
    rows: 1
    repository: vercel/next.js
    state: open
  - extension: json
    widget: JsonStatus
    x: 0
    y: 1
    columns: 3
    rows: 1
    title: API Status
    url: https://api.example.com/health
    statuses:
      - assert: equals(status, ok)
        status: success
        label: API Online
```

## Loading configuration

Load a file (JSON or YAML) on the server with `configureFromFile`, or pass a
TypeScript object to `configure`:

```ts lineNumbers title="dashfy.server.ts"
await dashfy.configureFromFile('./dashfy.config.yml')
// or
dashfy.configure(dashfyConfig)
```


# Cursor plugin (/docs/cursor-plugin)

The Dashfy Cursor plugin bundles everything an AI agent needs to work in a Dashfy
project: the [**agent skill**](/docs/skills), **project rules**, and the **MCP
server** — in a single installable package. With it, Cursor can scaffold apps, search
and install extensions, set up widgets and data sources, and create dashboards as
code.

## What's in the bundle

| Part          | Description                                                                     |
| ------------- | ------------------------------------------------------------------------------- |
| Agent skill   | Principles, CLI/registry/MCP/config references, and setup/layout/address rules. |
| Project rules | Conventions activated for `dashfy.json`, `dashfy.config.yml`, and server files. |
| MCP server    | The [`dashfy mcp`](/docs/mcp) tools for discovering and installing extensions.  |

The manifest ties these together:

```json
{
  "name": "dashfy",
  "displayName": "Dashfy",
  "skills": "./skills/",
  "rules": "./.cursor/rules/",
  "mcpServers": {
    "dashfy": {
      "command": "npx",
      "args": ["dashfy@latest", "mcp"]
    }
  }
}
```

## MCP-only setup

If you only want the MCP tools (without the skill and rules), configure the server
directly with the CLI:

```npm
npx dashfy@latest mcp init --client cursor
```

This writes `.cursor/mcp.json` with the `dashfy` server entry. See the
[MCP server](/docs/mcp) reference for the full list of tools and clients.

> **Pin the CLI**
>
> Add `--install` to pin `dashfy` as a devDependency and point the config at the local binary —
> handy for monorepos and teams that want a locked version.


# Deployment (/docs/deployment)

A Dashfy app is a long-running server that serves the built client and streams data
to it over WebSockets. Deploy it to any host that can run a persistent Node process.

## Requirements

Dashfy needs a runtime environment that supports:

* a **persistent Node process** — the server stays running to hold WebSocket
  connections (static and serverless-only hosts are not enough)
* **WebSockets** — real-time updates stream over a Socket.IO connection
* **environment variables** — for API tokens your extensions need (for example
  `GITHUB_TOKEN`)

In production the server serves the built client and handles the WebSocket
connection on a single `PORT`, so no separate frontend deployment is required.

## Production build

Projects scaffolded from any template are already set up for this — `pnpm build`
followed by `pnpm start` serves the dashboard and the WebSocket on one port. If you added
Dashfy to an existing app, two things need to line up.

The client must build into a directory the server serves as static files, which defaults
to `build/`:

```ts lineNumbers title="vite.config.ts"
export default defineConfig({
  plugins: [react()],
  build: {
    outDir: 'build',
    emptyOutDir: true,
  },
})
```

Frameworks that emit the client into a nested directory don't need a post-build move —
point the server at that directory with `staticDir` instead, which is resolved against
`baseDir` (requires `@getdashfy/server` 0.2.0 or later):

```yaml title="dashfy.config.yml"
staticDir: build/client
```

The templates split along those two lines: Astro sets `outDir: './build'`, while React
Router and TanStack Start keep their native output — `build/client` and `dist/client` —
and set `staticDir` to match.

And the client must connect to the same origin in production, rather than the
`localhost:5001` default it uses in development:

```tsx lineNumbers title="src/App.tsx"
export const App = () => {
  const serverUrl = import.meta.env.PROD ? window.location.origin : undefined

  return <Dashfy serverUrl={serverUrl} />
}
```

## One-click hosts

[Railway](https://railway.app) and [Render](https://render.com) both run a persistent
Node process with WebSockets. The official demo is preconfigured for either host —
`pnpm build` then `pnpm start`, with a health check at `/health`.

### Railway

Railway is the recommended host — it deploys the
[`dashfy-demo`](https://github.com/dashfy/dashfy-demo) project in one click via
`railway.toml`.

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/dashfy)

See the [demo repository](https://github.com/dashfy/dashfy-demo) for the full build and
start configuration.

### Render

Render also deploys [`dashfy-demo`](https://github.com/dashfy/dashfy-demo) in one click
via `render.yaml`. Enter a `GITHUB_TOKEN` when prompted if you use the GitHub extension.

[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/dashfy/dashfy-demo)

You can also create a **Web Service** in the Render dashboard, connect the repo, and use
the same build and start commands. A Blueprint is only needed if you want Render to
apply `render.yaml` automatically.

## Editing configuration

> **Fork or eject to change config**
>
> One-click deployments run from the upstream [`dashfy-demo`](https://github.com/dashfy/dashfy-demo)
> repository, so you do not get an editable copy on deploy. To persistently change
> `dashfy.config.yml` (or any source), **Eject** the service in Railway, or fork the demo and
> deploy from your fork on Railway or Render. Edits made only on the running container's
> filesystem are lost on the next deploy.

## Docker

Every template includes a `Dockerfile` that builds the client and runs the server in a
single container. From your project directory:

```bash
docker build -t my-dashfy-app .
docker run --rm -p 5001:5001 my-dashfy-app
```

The dashboard is then available at [http://localhost:5001](http://localhost:5001).

### Environment variables

Extension tokens are only read by the server at runtime, so nothing secret is baked into
the image. Pass them when you run the container:

```bash
docker run --rm -p 5001:5001 -e GITHUB_TOKEN=ghp_xxx my-dashfy-app
```

The server also honors `PORT` and binds `0.0.0.0`, which is what lets a platform assign
its own port:

```bash
docker run --rm -p 8080:8080 -e PORT=8080 my-dashfy-app
```

### Changing dashboards without rebuilding

Mount your config over the copy inside the image. The server watches the file, so edits
apply without restarting the container:

```bash
docker run --rm -p 5001:5001 \
  -v "$(pwd)/dashfy.config.yml:/app/dashfy.config.yml:ro" \
  my-dashfy-app
```

### Reproducible builds

Templates ship without a lockfile, so the included `Dockerfile` runs a plain
`pnpm install`. Commit `pnpm-lock.yaml` after your first install, then change the install
steps to `pnpm install --frozen-lockfile` so every rebuild resolves the same versions.

> **System widgets measure the container**
>
> Widgets from the system extension report the container's CPU, memory, and processes rather than
> the Docker host's. Monitoring the host itself requires granting the container extra access, such
> as `--pid=host` and a mounted `/proc`.

## Other hosts

Dashfy runs anywhere you can keep a Node process alive with WebSocket support — for
example [Fly.io](https://fly.io) or your own VPS. The [Docker](#docker) image works on
any host that can run containers.

## Live reference

The official demo runs the single-port production build described above at
[demo.dashfy.dev](https://demo.dashfy.dev).


# Extensions (/docs/extensions)

Extensions are how Dashfy connects to your stack. Each extension is an
`@getdashfy/ext-*` npm package that provides **widgets** (visual components) and,
optionally, a **server API client** (data source) plus setup metadata.

Extensions are resolved from a [registry](/docs/registry) at runtime over HTTP — the
same model as [shadcn/ui's component registry](https://ui.shadcn.com/docs/registry). The difference: a Dashfy registry item
describes an npm package plus setup metadata, so "applying" an extension means
*installing* the package and running codemods, rather than copying source files.

See available extensions [here](https://dashfy.dev/extensions).

## Add an extension

```npm
npx dashfy@latest add @getdashfy/github
```

`add` resolves the extension address from the registry, installs the npm package,
and sets it up automatically:

* registers widgets in your `App.tsx` via `WidgetRegistry.addExtension`
* registers the server API in your server bootstrap via `dashfy.registerApi`
* adds required environment variables to `.env`
* appends a starter widget block to your `dashfy.config.yml`

With no arguments, `add` fetches the catalog and prompts you to pick. Any
`registryDependencies` an item declares are resolved and applied first.

> **Setup is automatic — and reversible**
>
> Prefer the CLI over setting extensions up by hand. `dashfy add` and `dashfy remove` are
> idempotent, so re-running them is safe.

## Remove an extension

```npm
npx dashfy@latest remove @getdashfy/github
```

`remove` reverses what `add` set up: it removes the widget registration and
imports, the server API registration, and the starter dashboard. It uninstalls the
package (unless `--keep-deps`) and removes the extension's `.env` entries — but
**only when they are still empty placeholders**. Lines that hold a value are
preserved and reported, so your secrets are never deleted.

## Audit your project

`doctor` verifies that each extension is fully set up — its dependency is installed,
its widgets are registered, its server API is registered, its env vars are set, and
its starter block exists. It exits non-zero on failure, making it a useful CI gate.

Auto-detect installed extensions:

```npm
npx dashfy@latest doctor
```

Machine-readable report for CI:

```npm
npx dashfy@latest doctor --json
```

See the [CLI reference](/docs/cli) for `add`, `remove`, `doctor`, `search`, `view`,
and `docs`, and [Registry](/docs/registry) for authoring and hosting your own
extensions.


# How it works (/docs/how-it-works)

Dashfy uses a **server–client architecture** to load, compose, and render
dashboards. Configuration flows into a server that connects to APIs, and data
streams to a client that renders widgets and updates in real time.

## Server

The Dashfy server is the runtime that powers dashboards. It is responsible for:

* loading dashboard configuration
* connecting to APIs and data sources
* managing real-time data updates
* exposing data to clients via WebSockets

## Client

The Dashfy client renders dashboards using composable widgets and extensions. It
connects to the server and:

* receives real-time data updates
* renders widgets and layouts
* manages dashboard state and interactions

## Extensions

Dashfy is extensible through [extensions](/docs/extensions), which provide:

* widgets (visual components)
* data source integrations
* custom logic and transformations

This lets Dashfy connect to any API, service, or system without modifying the core.

## Runtime flow

### Load configuration

Dashfy loads the dashboard configuration (TypeScript, JSON, or YAML).

### Connect to APIs

The server connects to APIs and data sources through the registered extension
clients.

### Connect the client

The client opens a WebSocket connection to the server.

### Render and update

Dashfy renders the dashboard and pushes updates to the client in real time as data
changes.

> **Real-time by default**
>
> Dashfy is built around WebSockets and subscriptions — there are no polling hacks or manual
> refreshes. Dashboards update automatically as their underlying data changes.


# Introduction (/docs)

**Dashfy** is an open-source framework for building dashboards using declarative
configuration. Instead of manually building dashboards in a UI, you define them as
structured configuration. Dashfy connects to APIs and data sources, composes
widgets, and renders real-time interfaces.

Dashfy is designed to make dashboards developer-friendly, composable, extensible,
and maintainable. It is published as a set of npm packages (for example
`@getdashfy/server`, `@getdashfy/ui`, `@getdashfy/themes`, and `@getdashfy/ext-*`), and the
[`dashfy CLI`](/docs/cli) scaffolds new apps and resolves extensions from a hosted
registry.

> **Live demo**
>
> A live demo is available at [demo.dashfy.dev](https://demo.dashfy.dev).

## Why Dashfy

Developers build dashboards to monitor systems, track metrics, visualize APIs, and
power internal tools — but building and maintaining them is harder than it should
be. Traditional dashboards are often:

* tightly coupled to UI implementations
* difficult to version and review
* hard to extend and evolve
* manually constructed and maintained

Dashfy treats dashboards as **structured configuration** instead of handcrafted UI.
You define dashboards declaratively, connect APIs and data sources, and Dashfy
handles rendering, real-time updates, and composition. The result is dashboards
that are easier to maintain, version, extend, and reproduce across environments.

## How Dashfy is different

Dashfy is designed around a simple principle: dashboards should be defined as code,
not built manually in a UI.

* **Declarative, not manual** — dashboards are defined using structured
  configuration, making them easy to version, review, and maintain.
* **Developer-first** — integrates naturally with version control, CI/CD, code
  review, and infrastructure as code.
* **API-native** — connects directly to APIs and data sources through extensions,
  not tied to a specific backend or database.
* **Extensible architecture** — extensions add widgets and data sources without
  modifying the core.
* **Real-time by default** — a server–client architecture built on WebSockets and
  subscriptions, with no polling hacks or manual refresh.
* **Composable and reproducible** — dashboards can be versioned, reused, shared,
  and reproduced across environments.

## Where to go next

* [Installation](/docs/installation) — scaffold a new Dashfy project.
* [Quick start](/docs/quick-start) — set up the server and client together.
* [Configuration](/docs/configuration) — define dashboards in TypeScript, JSON, or YAML.
* [CLI](/docs/cli) — scaffold apps and manage extensions.
* [Deployment](/docs/deployment) — ship a Dashfy app to production.


# MCP server (/docs/mcp)

`dashfy mcp` runs a [Model Context Protocol](https://modelcontextprotocol.io) server
over stdio so AI assistants (Cursor, Claude, VS Code, Codex, OpenCode) can discover
and install Dashfy extensions. Tool output is plain text, and the server uses stdout
for the protocol only — it never logs to stdout.

## Tools

| Tool                         | Description                                                                      |
| ---------------------------- | -------------------------------------------------------------------------------- |
| `get_project_registries`     | List the registries configured for the project (plus built-in `@getdashfy`).     |
| `list_items_in_registries`   | List extensions across registries (filter by `types`, paginate).                 |
| `search_items_in_registries` | Fuzzy-search extensions by text query (ranked, paginated; runner-aware command). |
| `view_items_in_registries`   | Full details for one or more extensions (deps, env vars, setup).                 |
| `get_docs_for_items`         | Setup-oriented docs (env, setup, starter blocks, runner-aware install command).  |
| `get_add_command_for_items`  | The add command (and variants), prefixed with the project's package runner.      |
| `get_audit_checklist`        | Project-aware post-install checklist (env vars, server setup, starters).         |

## Configure a client

`dashfy mcp init` writes the client configuration that points to
`npx dashfy@latest mcp`. With no `--client`, it prompts you to select one or more.

```npm
npx dashfy@latest mcp init --client cursor
```

| Client   | File written       | Notes                                  |
| -------- | ------------------ | -------------------------------------- |
| Cursor   | `.cursor/mcp.json` | `mcpServers.dashfy`                    |
| Claude   | `.mcp.json`        | `mcpServers.dashfy`                    |
| VS Code  | `.vscode/mcp.json` | `servers.dashfy`                       |
| OpenCode | `opencode.json`    | `mcp.dashfy` (local)                   |
| Codex    | *none*             | prints TOML for `~/.codex/config.toml` |

Existing config files are preserved; only the `dashfy` server entry is merged in.

## Pin the CLI version

Pass `--install` to install `dashfy` as an exact devDependency (using your detected
package manager) and point the MCP config at the local binary (`npx dashfy mcp`)
instead of `npx dashfy@latest mcp`. This is useful for monorepos and teams that want
a locked CLI version.

```npm
npx dashfy@latest mcp init --client cursor --install
```

| Flag                | Description                                            |
| ------------------- | ------------------------------------------------------ |
| `-c, --cwd <cwd>`   | Working directory (on the `mcp` command).              |
| `--client <client>` | `cursor`, `claude`, `vscode`, `codex`, or `opencode`.  |
| `--install`         | Install `dashfy` as a pinned devDependency and use it. |

> **Using Cursor?**
>
> The [Cursor plugin](/docs/cursor-plugin) bundles this MCP server together with the [Dashfy agent
> skill](/docs/skills) and project rules in a single installable package.


# Quick start (/docs/quick-start)

A Dashfy app has two halves: a **server** that loads configuration and connects to
APIs, and a **client** that renders widgets and receives real-time updates over
WebSockets.

## Create a server

Create a Dashfy server, load a dashboard configuration, and register the API
clients your widgets need:

```ts lineNumbers title="dashfy.server.ts"
import { createJsonClient } from '@getdashfy/ext-json/client'
import { createGitHubClient } from '@getdashfy/ext-github/client'
import { Dashfy } from '@getdashfy/server'

// Create server instance
const dashfy = new Dashfy()

// Load dashboard configuration from a file (JSON or YAML):
await dashfy.configureFromFile('./dashfy.config.yml')

// or from a TypeScript object:
// import type { DashfyConfig } from '@getdashfy/types'
// const dashfyConfig: DashfyConfig = {...}
// dashfy.configure(dashfyConfig)

// Register JSON API
dashfy.registerApi('json', createJsonClient())

// Register GitHub API
dashfy.registerApi(
  'github',
  createGitHubClient({
    token: process.env.GITHUB_TOKEN!,
  }),
)

// Start server
await dashfy.start()
// Server running at http://0.0.0.0:5001
```

## Register widgets in React

On the client, register each extension's widgets with the `WidgetRegistry`, then
render the `<Dashfy />` component:

```tsx lineNumbers title="src/App.tsx"
import { CustomJson, JsonKeys, JsonStatus } from '@getdashfy/ext-json'
import {
  Branches,
  CommitActivityLine,
  ContributorsStats,
  Gitmap,
  OrgBadge,
  PullRequests,
  RepoBadge,
  Status,
  TrafficClonesHistogram,
  TrafficViewsHistogram,
  UserBadge,
} from '@getdashfy/ext-github'
import { Dashfy, WidgetRegistry } from '@getdashfy/ui'

// Register GitHub extension
WidgetRegistry.addExtension('github', {
  Branches,
  CommitActivityLine,
  ContributorsStats,
  Gitmap,
  OrgBadge,
  PullRequests,
  RepoBadge,
  Status,
  TrafficClonesHistogram,
  TrafficViewsHistogram,
  UserBadge,
})

// Register JSON extension
WidgetRegistry.addExtension('json', {
  CustomJson,
  JsonKeys,
  JsonStatus,
})

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

> **Let the CLI set it up for you**
>
> Running [`dashfy add`](/docs/cli) performs both steps automatically — it registers widgets in
> `App.tsx`, registers the server API in your bootstrap, adds the required `.env` entries, and seeds
> a starter dashboard block.

## Next steps

* [Configuration](/docs/configuration) — the full dashboard configuration model.
* [How it works](/docs/how-it-works) — the server–client runtime flow.
* [Extensions](/docs/extensions) — connect Dashfy to your stack.
* [Deployment](/docs/deployment) — deploy your app to production.


# Registry (/docs/registry)

Extensions are resolved from a **registry** at runtime over HTTP — the same model as
[shadcn/ui](https://ui.shadcn.com/docs/registry). The default registry is the `@getdashfy` namespace, served from
`https://registry.dashfy.dev/r`. A Dashfy registry item describes an npm package plus
setup metadata, so "applying" an extension installs the package and runs codemods,
rather than copying source files.

## Registry items

Each extension publishes a `<name>.json` registry item that validates against
[`registry-item.json`](https://dashfy.dev/schema/registry-item.json). It describes
the npm package, its dependencies, required environment variables, the widgets it
provides, and a starter dashboard block. Items can declare `registryDependencies`,
which are resolved and applied first when the item is added.

The item's `docs` field (surfaced by `dashfy docs` and the MCP `get_docs_for_items`
tool) is authored in each extension's `package.json` under `dashfy.docs` and copied
into the registry item by `dashfy registry build`.

## Custom & third-party registries

Anyone can publish a registry: serve `<name>.json` files plus an `index.json` catalog
at a public URL, declare the namespace in your `dashfy.json`, and install with
`dashfy add @yourscope/widget`. Items can also live in a GitHub repo (under
`r/<name>.json`) and be installed with `dashfy add owner/repo/widget`.

```json
{
  "registries": {
    "@acme": "https://acme.com/r/{name}.json"
  }
}
```

For private/authenticated registries, use the object form with `${ENV_VAR}`
placeholders that resolve from your `.env`:

```json
{
  "registries": {
    "@acme": {
      "url": "https://acme.com/r/{name}.json",
      "headers": { "Authorization": "Bearer ${ACME_TOKEN}" }
    }
  }
}
```

## `dashfy registry add [registries...]`

Adds custom registries to your `dashfy.json` (merged over the built-in `@getdashfy`).
Accepts a bare namespace resolved from the discovery index, or an explicit
`namespace=url` pair.

Resolve @acme from the hosted discovery index:

```npm
npx dashfy@latest registry add @acme
```

Declare a namespace with an explicit URL template (must contain `{name}`):

```npm
npx dashfy@latest registry add @acme=https://acme.com/r/{name}.json
```

## `dashfy registry remove [registries...]`

Removes custom registries from your `dashfy.json` — the inverse of `registry add`.
Removing a namespace that is not configured is a safe no-op, and the built-in
`@getdashfy` namespace can never be removed.

```npm
npx dashfy@latest registry remove @acme
```

## Discovery index (`registries.json`)

The CLI resolves bare namespaces from a hosted discovery index at
`https://registry.dashfy.dev/registries.json`, which maps each public `@namespace` to
its URL template plus optional `name`, `description`, and `homepage`. Override its
location with `DASHFY_REGISTRIES_URL` for offline work or testing.

## `dashfy registry build [packages]`

Builds the hosted registry artifacts (`<name>.json` per extension + `index.json`)
from the `dashfy` metadata field of each extension.

With `--from-npm` it reads the latest manifest each listed package has published.
This is how the files served at `registry.dashfy.dev` are produced: extensions live
in their own repositories, so npm — not any single checkout — is the source of truth
for what the catalog serves.

```npm
npx dashfy@latest registry build --from-npm apps/registry/extensions.json
```

The list file is `{ "packages": ["@scope/ext-name", ...] }`. A package that cannot be
fetched or has no `dashfy` field fails the build instead of being skipped, so a
transient error cannot publish a catalog that is missing extensions. Override the npm
origin with `DASHFY_NPM_REGISTRY_URL` to build against a mirror or a local directory
of manifests.

Without `--from-npm`, the command reads local `ext-*` package directories instead.
Use this to preview an extension's registry item before publishing it:

```npm
npx dashfy@latest registry build ./packages
```

| Flag                    | Description                                         |
| ----------------------- | --------------------------------------------------- |
| `[packages]`            | Directory with the `ext-*` packages (`./packages`). |
| `-n, --from-npm <path>` | JSON file listing published packages to build from. |
| `-o, --output <path>`   | Destination directory (`apps/registry/public/r`).   |
| `-c, --cwd <cwd>`       | Working directory.                                  |

## `dashfy registry validate [dir]`

Validates a built registry directory before publishing: it checks that `index.json`
and every `<name>.json` match the schemas, that filenames match item names, that
there are no duplicates, that the index is in sync, and that local
`registryDependencies` resolve within the same registry. Exits non-zero on failure.

```npm
npx dashfy@latest registry build && npx dashfy@latest registry validate
```


# Skills (/docs/skills)

Skills give AI assistants like Cursor, Claude Code, and Codex project-aware context
about Dashfy. When installed, your agent knows how to scaffold apps, find and install
extensions, set up widgets and data sources, and create dashboards using the correct
CLI, registry, and MCP APIs for your project.

For example, you can ask your AI assistant to:

* *"Add the GitHub extension and show my repo's pull requests."*
* *"Scaffold a new dashboard app with the system monitor extension."*
* *"Create a dashboard with CPU, memory, and disk widgets."*
* *"Find an extension for my JSON API and set it up."*

The skill reads your project (`dashfy.json`, `dashfy.config.yml`, installed
`@getdashfy/ext-*` packages) and provides the assistant with the detected paths,
configured registries, and available widgets so it can generate correct code on the
first try.

## Install

Add the Dashfy skill to your AI agent with the [`skills`](https://skills.sh) CLI:

```npm
npx skills add dashfy/dashfy
```

This detects the agents installed in your project and writes the skill into each one's
directory. Learn more about agent skills at [skills.sh](https://skills.sh).

> **Using Cursor?**
>
> The [Cursor plugin](/docs/cursor-plugin) bundles the skill together with the project rules and the
> [MCP server](/docs/mcp) in a single installable package.

## What's included

The skill provides your AI assistant with the following knowledge:

### Project context

The skill runs `dashfy info --json` to read your project configuration: detected
files, `dashfy.json` paths, configured registries, and installed `@getdashfy/ext-*`
packages. This grounds every suggestion in your actual project.

### CLI commands

Full reference for every command — `init`, `add`, `remove`, `search`, `view`, `docs`,
`info`, `doctor`, `registry`, and `mcp` — including flags and dry-run mode. See the
[CLI reference](/docs/cli).

### Registry and addresses

How extensions are resolved from registries, how to classify an address (bare name,
`@namespace/name`, `owner/repo/name`, URL, or local file), and how to author and host
custom registries. See [Registry](/docs/registry).

### Dashboard layout

The widget grid rules — every widget needs `extension`, `widget`, `x`, `y`, `columns`,
and `rows`; widgets stay inside the grid and must not overlap; only registered widgets
may be referenced. See [Configuration](/docs/configuration).

### MCP tools

The tools exposed by the `dashfy mcp` server so agents can discover and install
extensions programmatically. See the [MCP server](/docs/mcp).

## How it works

### Project detection

The skill activates when it finds a `dashfy.json` or `dashfy.config.yml` in your
project.

### Context injection

It runs `dashfy info --json` and injects the result into the assistant's context, so
suggestions reflect your detected files, registries, and installed extensions.

### Pattern enforcement

The assistant follows Dashfy conventions: it uses `dashfy add` / `dashfy remove`
codemods instead of manual setup, keeps widgets within the dashboard grid, and
classifies registry addresses correctly (bare names resolve to `@getdashfy`).

### Extension discovery

Before generating code, the assistant uses `dashfy search`, `dashfy docs`, or the MCP
tools to find extensions and read their setup documentation.

### Verification

After adding an extension, the assistant runs `dashfy doctor` to confirm the package,
widget registration, server API, environment variables, and starter block are all in
place.

## Using with other agents

The skill is a standard agent skill (a `SKILL.md` with `name` and `description`), so
the same install works across Claude Code, Codex, Copilot, Cline, Zed, and the other
agents the `skills` CLI supports. Target specific ones with `--agent`:

```npm
npx skills add dashfy/dashfy --agent claude-code
```

Two Dashfy-specific notes:

* **Cursor** — the [Cursor plugin](/docs/cursor-plugin) is the richer option, bundling
  the skill together with the project rules and the MCP server.
* **MCP tools** — the skill tells your agent which CLI commands to run, but the
  [MCP server](/docs/mcp) is configured separately with `dashfy mcp init`.

## Learn more

* [CLI](/docs/cli) — every command, flag, and example.
* [MCP server](/docs/mcp) — tools for discovering and installing extensions.
* [Registry](/docs/registry) — authoring and hosting extension registries.
* [Cursor plugin](/docs/cursor-plugin) — the skill, rules, and MCP in one package.
* [Configuration](/docs/configuration) — the dashboard configuration model.


# Themes (/docs/themes)

Dashfy ships with built-in themes and supports light/dark mode out of the box, plus
custom themes through the `@getdashfy/themes` package.

## Built-in themes

Dashfy includes several ready-to-use themes, including the **Default**, **Midnight
Blue**, and **Nord** themes. Each theme supports both light and dark variants, and
the active theme is part of your dashboard experience — not something you set up by
hand in the UI.

## Light & dark mode

Theme support includes automatic light/dark mode. Dashboards adapt to the selected
mode so they look right whether they run on a developer's laptop or a wall display.

## Custom themes

Use `@getdashfy/themes` to define and apply custom themes for your dashboards. This lets
you align Dashfy with your brand or environment while keeping the declarative,
config-driven workflow.

> **Built for displays**
>
> Dashfy also supports fullscreen mode, dashboard rotation, and wake lock — useful for TV dashboards
> and kiosk-style monitoring screens running continuously.

## Related

* [Configuration](/docs/configuration) — define dashboards and widgets.
* [How it works](/docs/how-it-works) — the server–client runtime.


# Astro (/docs/installation/astro)

Dashfy renders the dashboard as a client-only React island in your Astro app, plus
a separate Dashfy Node server that streams data over Socket.IO.

- [Use the CLI Scaffold a ready-to-run Astro project from the terminal.](#use-the-cli)

- [Existing project Add Dashfy manually to an app you already created.](#existing-project)



## Use the CLI

### Create a new app

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

```npm
npx dashfy@latest init -t astro-starter
```

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

```npm
npx 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`):

```npm
npm install
```

### Start developing

Run the Astro app and the Dashfy server together:

```npm
npm run dev:all
```

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



## Existing project

### Install Dashfy

Add the Astro React integration:

```npm
npx astro add react
```

Add the Dashfy runtime packages:

```package-install
@getdashfy/server @getdashfy/ui
```

And the dev tooling used to run the server:

```npm
npm install -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:

```ts title="dashfy.server.ts"
import { Dashfy } from '@getdashfy/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:

```yaml title="dashfy.config.yml"
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`:

```tsx title="src/components/DashfyApp.tsx"
import '@getdashfy/ui/styles.css'

import { Dashfy, ThemeRegistry } from '@getdashfy/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:

```astro title="src/pages/index.astro"
---
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`:

```js title="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:

```json title="package.json"
{
  "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`:

```json title="dashfy.json"
{
  "$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](http://localhost:3000):

```npm
npm run dev:all
```

## Add extensions

With `dashfy.json` in place, add extensions (widgets + data sources) from the
registry. The CLI installs the package and sets it up in
`src/components/DashfyApp.tsx`, `dashfy.server.ts`, `dashfy.config.yml`, and `.env`:

```npm
npx dashfy@latest add @getdashfy/github
```

See [Extensions](/docs/extensions) and the [CLI reference](/docs/cli) for details.

## Deploy

Scaffolded projects also include a `Dockerfile`, so `pnpm build && pnpm start` or a single
`docker build` gets you a production dashboard. See [Deployment](/docs/deployment) for
hosting options and the [Docker](/docs/deployment#docker) setup.


# Installation (/docs/installation)

The fastest way to start a Dashfy project is the [`dashfy CLI`](/docs/cli), which
scaffolds a runnable app and can set extensions up for you.

Available for Next.js, Vite, React Router, Astro, and TanStack Start.

## Scaffold a project

### Create a new app

Run `init` to scaffold the minimal starter. You will be prompted to choose
extensions, which Dashfy sets up in the new project for you:

```npm
npx dashfy@latest init
```

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

```npm
npx dashfy@latest init -t vite-app
```

Supported templates: `vite-app`, `astro-app`, `next-app`, `react-router-app`, and `start-app`.

### Install dependencies

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

```npm
npm install
```

### Start developing

Run the dev server for both the client and server:

```npm
npm run dev:all
```

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

## Templates

The CLI provides these templates:

| Template               | Description                                                                           |
| ---------------------- | ------------------------------------------------------------------------------------- |
| `vite-starter`         | Minimal Vite app (default). The CLI prompts for extensions and sets them up.          |
| `vite-app`             | Full Vite demo with GitHub, System, and Market Live extensions, no prompts.           |
| `astro-starter`        | Minimal Astro app. The CLI prompts for extensions and sets them up.                   |
| `astro-app`            | Full Astro demo with GitHub, System, and Market Live extensions, no prompts.          |
| `next-starter`         | Minimal Next.js app. The CLI prompts for extensions and sets them up.                 |
| `next-app`             | Full Next.js demo with GitHub, System, and Market Live extensions, no prompts.        |
| `react-router-starter` | Minimal React Router app. The CLI prompts for extensions and sets them up.            |
| `react-router-app`     | Full React Router demo with GitHub, System, and Market Live extensions, no prompts.   |
| `start-starter`        | Minimal TanStack Start app. The CLI prompts for extensions and sets them up.          |
| `start-app`            | Full TanStack Start demo with GitHub, System, and Market Live extensions, no prompts. |

```npm
npx dashfy@latest init my-app -t [template]
```

## Choose your framework

Each framework guide includes a &#x2A;*"Use the CLI"*&#x2A; path and an &#x2A;*"Existing Project"**
section with the manual setup steps for that framework. Pick your framework below.

- [Next.js](/docs/installation/next)

- [Vite](/docs/installation/vite)

- [React Router](/docs/installation/react-router)

- [Astro](/docs/installation/astro)

- [TanStack Start](/docs/installation/tanstack)

- [Manual](/docs/installation/manual)

## Add extensions

Extensions (widgets + data sources) are resolved from a hosted registry. Add one to
an existing project with `add`:

```npm
npx dashfy@latest add @getdashfy/github
```

This installs the `@getdashfy/ext-*` package and sets it up automatically: widgets are
registered in your app file (`App.tsx`, or the file set in `dashfy.json`), the server API is registered in your server bootstrap, required
environment variables are added to `.env`, and a starter widget block is appended to
your dashboard config. See [Extensions](/docs/extensions) and the [CLI
reference](/docs/cli) for details.


# Manual (/docs/installation/manual)

Dashfy runs as two processes: the React app that renders the dashboard UI, and a
separate Dashfy Node server that streams data over Socket.IO.

This guide covers wiring Dashfy into a React setup that isn't one of the dedicated
framework guides (for example Create React App, a custom webpack/Rspack build, or a
bespoke Vite config). If you're on a supported framework, the
[Next.js](/docs/installation/next), [Vite](/docs/installation/vite),
[React Router](/docs/installation/react-router), [Astro](/docs/installation/astro),
or [TanStack Start](/docs/installation/tanstack) guides are a smoother path.

### Install Dashfy

Add the Dashfy runtime packages:

```package-install
@getdashfy/server @getdashfy/ui
```

And the dev tooling used to run the server:

```npm
npm install -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:

```ts title="dashfy.server.ts"
import { Dashfy } from '@getdashfy/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:

```yaml title="dashfy.config.yml"
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`:

```tsx title="src/App.tsx"
import { Dashfy } from '@getdashfy/ui'

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

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

```tsx title="src/main.tsx"
import '@getdashfy/ui/styles.css'

import { ThemeRegistry } from '@getdashfy/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>,
)
```

> **Client-only rendering**
>
> `<Dashfy />` must render only in the browser. If your setup uses server-side rendering, load the
> dashboard client-side (e.g. lazily on mount) so it never renders on the server.

### 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`:

```ts title="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](/docs/installation/next),
[Astro](/docs/installation/astro), and
[React Router](/docs/installation/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:

```json title="package.json"
{
  "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`):

```json title="dashfy.json"
{
  "$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](http://localhost:3000):

```npm
npm run dev:all
```

## Add extensions

With `dashfy.json` in place, add extensions (widgets + data sources) from the
registry. The CLI installs the package and sets it up in your app file,
`dashfy.server.ts`, `dashfy.config.yml`, and `.env`:

```npm
npx dashfy@latest add @getdashfy/github
```

See [Extensions](/docs/extensions) and the [CLI reference](/docs/cli) for details.


# Next.js (/docs/installation/next)

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.

- [Use the CLI Scaffold a ready-to-run Next.js project from the terminal.](#use-the-cli)

- [Existing project Add Dashfy manually to an app you already created.](#existing-project)



## 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:

```npm
npx dashfy@latest init -t next-starter
```

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

```npm
npx dashfy@latest init -t next-app
```

### Install dependencies

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

```npm
npm install
```

### Start developing

Run the Next.js app and the Dashfy server together:

```npm
npm run dev:all
```

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



## Existing project

### Install Dashfy

Add the Dashfy runtime packages:

```package-install
@getdashfy/server @getdashfy/ui
```

And the dev tooling used to run the server:

```npm
npm install -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:

```ts title="dashfy.server.ts"
import { Dashfy } from '@getdashfy/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:

```yaml title="dashfy.config.yml"
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

The dashboard UI is client-only. Create `components/DashfyApp.tsx`:

```tsx title="components/DashfyApp.tsx"
'use client'

import '@getdashfy/ui/styles.css'

import { Dashfy, ThemeRegistry } from '@getdashfy/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`:

```tsx title="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`:

```ts title="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 nextConfig
```

### 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:

```json title="package.json"
{
  "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`:

```json title="dashfy.json"
{
  "$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](http://localhost:3000):

```npm
npm run dev:all
```

## Add 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`:

```npm
npx dashfy@latest add @getdashfy/github
```

See [Extensions](/docs/extensions) and the [CLI reference](/docs/cli) for details.


# React Router (/docs/installation/react-router)

Dashfy runs the React Router app in SPA mode (the dashboard UI is client-only) plus
a separate Dashfy Node server that streams data over Socket.IO.

- [Use the CLI Scaffold a ready-to-run React Router project from the terminal.](#use-the-cli)

- [Existing project Add Dashfy manually to an app you already created.](#existing-project)



## Use the CLI

### Create a new app

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

```npm
npx dashfy@latest init -t react-router-starter
```

Prefer the full, pre-configured demo? Use the
`react-router-app` template instead:

```npm
npx dashfy@latest init -t react-router-app
```

### Install dependencies

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

```npm
npm install
```

### Start developing

Run the React Router app and the Dashfy server together:

```npm
npm run dev:all
```

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



## Existing project

### Install Dashfy

Add the Dashfy runtime packages:

```package-install
@getdashfy/server @getdashfy/ui
```

And the dev tooling used to run the server:

```npm
npm install -D tsx dotenv-cli concurrently
```

### Enable SPA mode

The Dashfy UI is client-only, so disable SSR in `react-router.config.ts`:

```ts title="react-router.config.ts"
import type { Config } from '@react-router/dev/config'

export default {
  // SPA mode: the Dashfy UI is client-only and talks to a separate Node server.
  ssr: false,
} satisfies Config
```

Add a `HydrateFallback` to `app/root.tsx` so nothing renders during prerender:

```tsx title="app/root.tsx"
// SPA mode: render nothing during prerender; the client hydrates the dashboard.
export function HydrateFallback() {
  return null
}
```

### Create the Dashfy server

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

```ts title="dashfy.server.ts"
import { Dashfy } from '@getdashfy/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:

```yaml title="dashfy.config.yml"
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 `app/components/DashfyApp.tsx`:

```tsx title="app/components/DashfyApp.tsx"
import '@getdashfy/ui/styles.css'

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

ThemeRegistry.loadAllThemes()

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

Render it from your index route (`app/routes/home.tsx`):

```tsx title="app/routes/home.tsx"
import DashfyApp from '~/components/DashfyApp'

export function meta() {
  return [{ title: 'Dashfy' }]
}

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

### Proxy the config endpoint

The UI reads its configuration from `/config`. Proxy it to the Dashfy server in
`vite.config.ts`:

```ts title="vite.config.ts"
import { reactRouter } from '@react-router/dev/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  resolve: { tsconfigPaths: true },
  server: {
    port: 3000,
    proxy: {
      '/config': 'http://localhost:5001',
    },
  },
  plugins: [reactRouter()],
})
```

### 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:

```json title="package.json"
{
  "scripts": {
    "dev": "react-router 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`:

```json title="dashfy.json"
{
  "$schema": "https://dashfy.dev/schema.json",
  "registries": {},
  "paths": {
    "app": "app/components/DashfyApp.tsx",
    "server": "dashfy.server.ts",
    "config": "dashfy.config.yml",
    "env": ".env"
  }
}
```

### Start developing

Run everything together and open [http://localhost:3000](http://localhost:3000):

```npm
npm run dev:all
```

## Add extensions

With `dashfy.json` in place, add extensions (widgets + data sources) from the
registry. The CLI installs the package and sets it up in
`app/components/DashfyApp.tsx`, `dashfy.server.ts`, `dashfy.config.yml`, and `.env`:

```npm
npx dashfy@latest add @getdashfy/github
```

See [Extensions](/docs/extensions) and the [CLI reference](/docs/cli) for details.

## Deploy

Scaffolded projects also include a `Dockerfile`, so `pnpm build && pnpm start` or a single
`docker build` gets you a production dashboard. See [Deployment](/docs/deployment) for
hosting options and the [Docker](/docs/deployment#docker) setup.


# TanStack Start (/docs/installation/tanstack)

Dashfy runs TanStack Start in SPA mode (the dashboard UI is client-only) plus a
separate Dashfy Node server. The UI connects to the server over Socket.IO, which
delivers the dashboard configuration on connect.

- [Use the CLI Scaffold a ready-to-run TanStack Start project from the terminal.](#use-the-cli)

- [Existing project Add Dashfy manually to an app you already created.](#existing-project)



## Use the CLI

### Create a new app

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

```npm
npx dashfy@latest init -t start-starter
```

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

```npm
npx dashfy@latest init -t start-app
```

### Install dependencies

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

```npm
npm install
```

### Start developing

Run the TanStack Start app and the Dashfy server together:

```npm
npm run dev:all
```

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



## Existing project

### Install Dashfy

Add the Dashfy runtime packages:

```package-install
@getdashfy/server @getdashfy/ui
```

And the dev tooling used to run the server:

```npm
npm install -D tsx dotenv-cli concurrently
```

### Enable SPA mode

The Dashfy UI is client-only, so enable SPA mode in `vite.config.ts`:

```ts title="vite.config.ts"
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import viteReact from '@vitejs/plugin-react'
import { defineConfig } from 'vite'

export default defineConfig({
  resolve: { tsconfigPaths: true },
  server: { port: 3000 },
  // SPA mode: the Dashfy UI is client-only and talks to a separate Node server.
  plugins: [tanstackStart({ spa: { enabled: true } }), viteReact()],
})
```

> **No config proxy needed**
>
> Unlike the other frameworks, TanStack Start does not proxy `/config`. The Dashfy UI receives its
> configuration directly from the server over Socket.IO on connect.

### Create the Dashfy server

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

```ts title="dashfy.server.ts"
import { Dashfy } from '@getdashfy/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:

```yaml title="dashfy.config.yml"
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`:

```tsx title="src/components/DashfyApp.tsx"
import '@getdashfy/ui/styles.css'

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

ThemeRegistry.loadAllThemes()

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

Render it from your index route (`src/routes/index.tsx`):

```tsx title="src/routes/index.tsx"
import { createFileRoute } from '@tanstack/react-router'

import DashfyApp from '@/components/DashfyApp'

export const Route = createFileRoute('/')({ component: DashfyApp })
```

### 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:

```json title="package.json"
{
  "scripts": {
    "dev": "vite dev --port 3000",
    "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`:

```json title="dashfy.json"
{
  "$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](http://localhost:3000):

```npm
npm run dev:all
```

## Add extensions

With `dashfy.json` in place, add extensions (widgets + data sources) from the
registry. The CLI installs the package and sets it up in
`src/components/DashfyApp.tsx`, `dashfy.server.ts`, `dashfy.config.yml`, and `.env`:

```npm
npx dashfy@latest add @getdashfy/github
```

See [Extensions](/docs/extensions) and the [CLI reference](/docs/cli) for details.

## Deploy

Scaffolded projects also include a `Dockerfile`, so `pnpm build && pnpm start` or a single
`docker build` gets you a production dashboard. See [Deployment](/docs/deployment) for
hosting options and the [Docker](/docs/deployment#docker) setup.


# Vite (/docs/installation/vite)

Dashfy runs as two processes: the Vite app that renders the dashboard UI, and a
separate Dashfy Node server that streams data over Socket.IO.

- [Use the CLI Scaffold a ready-to-run Vite project from the terminal.](#use-the-cli)

- [Existing project Add Dashfy manually to an app you already created.](#existing-project)



## Use the CLI

### Create a new app

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

```npm
npx dashfy@latest init -t vite-starter
```

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

```npm
npx dashfy@latest init -t vite-app
```

### Install dependencies

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

```npm
npm install
```

### Start developing

Run the Vite app and the Dashfy server together:

```npm
npm run dev:all
```

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



## Existing project

### Install Dashfy

Add the Dashfy runtime packages:

```package-install
@getdashfy/server @getdashfy/ui
```

And the dev tooling used to run the server:

```npm
npm install -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:

```ts title="dashfy.server.ts"
import { Dashfy } from '@getdashfy/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:

```yaml title="dashfy.config.yml"
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`:

```tsx title="src/App.tsx"
import { Dashfy } from '@getdashfy/ui'

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

Import the styles and load the themes in `src/main.tsx`:

```tsx title="src/main.tsx"
import '@getdashfy/ui/styles.css'

import { ThemeRegistry } from '@getdashfy/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>,
)
```

### Proxy the config endpoint

The UI reads its configuration from `/config`. Proxy it to the Dashfy server in
`vite.config.ts`:

```ts title="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',
    },
  },
})
```

### 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:

```json title="package.json"
{
  "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`:

```json title="dashfy.json"
{
  "$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](http://localhost:3000):

```npm
npm run dev:all
```

## Add extensions

With `dashfy.json` in place, add extensions (widgets + data sources) from the
registry. The CLI installs the package and sets it up in `src/App.tsx`,
`dashfy.server.ts`, `dashfy.config.yml`, and `.env`:

```npm
npx dashfy@latest add @getdashfy/github
```

See [Extensions](/docs/extensions) and the [CLI reference](/docs/cli) for details.

## Deploy

Scaffolded projects also include a `Dockerfile`, so `pnpm build && pnpm start` or a single
`docker build` gets you a production dashboard. See [Deployment](/docs/deployment) for
hosting options and the [Docker](/docs/deployment#docker) setup.