CLI Usage

grafana-react includes a CLI for building and validating dashboards.

npx grafana-react build my-dashboard.tsx

Commands

build

Build a single dashboard file to JSON:

npx grafana-react build <input.tsx> [output.json]

Arguments:

• input.tsx - Path to the dashboard file
• output.json - (Optional) Output path. If omitted, prints to stdout.

Examples:

# Output to stdout
npx grafana-react build my-dashboard.tsx

# Output to file
npx grafana-react build my-dashboard.tsx output/my-dashboard.json

build-all

Build all dashboard files in a directory:

npx grafana-react build-all <input-dir> [output-dir]

Finds all *.dashboard.tsx files and builds them.

Arguments:

• input-dir - Directory containing dashboard files
• output-dir - (Optional) Output directory. Defaults to same as input.

Examples:

# Build all dashboards, output alongside source files
npx grafana-react build-all ./dashboards

# Build to separate output directory
npx grafana-react build-all ./dashboards ./output

validate

Validate a dashboard without generating output:

npx grafana-react validate <input.tsx>

Checks that the dashboard:

• Parses correctly
• Has valid component structure
• Has required props

Examples:

npx grafana-react validate my-dashboard.tsx

watch

Watch for changes and rebuild automatically:

npx grafana-react watch <input-dir> [output-dir]

Watches all *.dashboard.tsx files and rebuilds on change.

Arguments:

• input-dir - Directory to watch
• output-dir - (Optional) Output directory

Examples:

# Watch and build in place
npx grafana-react watch ./dashboards

# Watch with separate output
npx grafana-react watch ./dashboards ./output

File Naming Convention

Dashboard files should be named with the .dashboard.tsx suffix:

my-dashboard.tsx
system-overview.dashboard.tsx
api-monitoring.dashboard.tsx

The CLI uses this pattern to identify dashboard files.

Output Format

The generated JSON is formatted and ready for import into Grafana:

{
  "uid": "my-dashboard",
  "title": "My Dashboard",
  "tags": ["monitoring"],
  "panels": [...],
  "templating": {...},
  ...
}

Exit Codes

Code	Meaning
0	Success
1	Build error (invalid JSX, missing props, etc.)
2	File not found

Integration with Build Systems

package.json scripts

{
  "scripts": {
    "build:dashboards": "grafana-react build-all ./dashboards ./output",
    "dev:dashboards": "grafana-react watch ./dashboards ./output"
  }
}

CI/CD

# GitHub Actions example
- name: Build dashboards
  run: npx grafana-react build-all ./dashboards ./output

- name: Upload dashboards
  uses: actions/upload-artifact@v4
  with:
    name: dashboards
    path: output/*.json