Dashboard Guide

ACMS includes an optional dev dashboard for visual content editing. The dashboard is a pre-built Vite/React app that wraps @useacms/editor components and is served as static files by the CLI dev server.

The dashboard is entirely optional — you can always edit acms.json directly, use the REST API, or build a custom UI.

Overview

The dashboard provides:

• Visual editors for all field types (string, text, number, boolean, array, image, location, color, markdown, calendar)
• Field type management — change a field’s type via the metadata system
• Field creation and deletion
• Real-time updates via Server-Sent Events (SSE)
• Fields organized by top-level groups (e.g., hero.*, contact.*)
• Search and filtering

Setup

Install the Dashboard Package

The dashboard is distributed as an npm package. Install it as a dev dependency:

# npm
npm install -D @useacms/dev-dashboard

# pnpm
pnpm add -D @useacms/dev-dashboard

# yarn
yarn add -D @useacms/dev-dashboard

Start the Dev Server

The CLI automatically detects and serves the dashboard — no extra terminals needed:

acms dev

Visit http://localhost:4185/dashboard to open the dashboard.

If you use a custom port, the dashboard is served there too:

3002/dashboard

acms dev -p 3002

Disabling the Dashboard

To start the dev server without the dashboard:

acms dev --no-dashboard

Dashboard Not Loading?

If http://localhost:4185/dashboard returns a 404, the @useacms/dev-dashboard package is not installed. Install it and restart the dev server.

Field Editors

The dashboard provides type-specific editors for each field:

String Fields

Single-line text input for short content like titles, labels, and names.

Text Fields

Multi-line textarea for longer content like descriptions, paragraphs, and body copy.

Number Fields

Numeric input with validation. Prevents non-numeric input.

Boolean Fields

Toggle switch for true/false values like feature flags, visibility toggles, and settings.

Array Fields

List editor with:

• Add — Append new items to the array
• Remove — Delete individual items
• Reorder — Drag to reorder items in the list

Color Fields

Hex color picker with:

• Color picker — Native browser color picker for visual selection
• Hex input — Enter hex values directly (e.g., #ff0000)
• Swatch preview — Live preview of the selected color

Markdown Fields

Rich markdown editor with:

• Write/preview tabs — Toggle between editing and rendered preview
• Formatting toolbar — Bold, italic, strikethrough, code, headings, lists, blockquote, link
• Live preview — Rendered HTML preview with sanitization
• Auto-save — Changes saved automatically with debounce

Calendar Fields

Event calendar editor with:

• Event list — Events sorted by start date with color-coded indicators
• Month grid view — Calendar grid with event indicators and navigation
• Add/edit/delete events — Full CRUD via dialog with title, dates, all-day toggle, description, location, color, and URL fields
• Custom properties — Support for propsSchema metadata to define custom event fields
• Auto-generated IDs — Events automatically receive UUID identifiers

Location Fields

Latitude/longitude coordinate editor with:

• Number inputs — Enter lat and lng values directly
• Map picker — Click a MapLibre GL map to set coordinates (optional, requires maplibre-gl)

Field Type Management

Each field displays a type badge (e.g., “string”, “text”, “number”). Click the badge to change the field’s type. The type determines which editor is shown and how the value is validated.

Available types:

Type	Description
string	Short text, single line
text	Long text, multi-line
number	Numeric values
boolean	True or false
array	Ordered list of items
object	Nested field group
image	Image URL with preview
location	Map coordinates (lat/lng)
color	Hex color picker
markdown	Markdown editor with write/preview
calendar	Event calendar with list and grid views

Creating Fields

Use the “Add Field” form to create new fields:

1. Enter the field path (e.g., hero.ctaText)
2. Select a field type
3. Optionally set an initial value
4. Click “Create”

The field is added to acms.json and appears in the dashboard immediately.

Deleting Fields

Click the delete button on any field to remove it. A confirmation dialog prevents accidental deletions. Deleting a field removes both its value and metadata from acms.json.

Real-Time Updates

The dashboard uses Server-Sent Events (SSE) to stay in sync with the dev server. When acms.json changes (from any source — direct editing, API calls, or another dashboard tab), all connected dashboards update automatically.

This means:

• Multiple team members can edit simultaneously
• Changes from code (field registration) appear instantly
• External edits to acms.json are reflected in real-time

Grouped View

Fields are organized by their top-level key. For example:

hero
  ├── title: "Welcome to ACMS"
  ├── subtitle: "Schema-less CMS"
  └── ctaText: "Get Started"

contact
  ├── email: "hello@example.com"
  └── phone: "+1 234 567 890"

name: "My Site"

Top-level fields (like name) appear in an ungrouped section.

Search

Use the search bar to filter fields by path or value. Searching for “hero” shows all fields under the hero group. Searching for “email” shows any field whose path or value contains “email”.

Building a Custom Dashboard

If the reference dashboard doesn’t meet your needs, you can build a custom editing UI using the REST API. All CRUD operations are available:

// Fetch all fields
const schema = await fetch('http://localhost:4185/api/schema').then(r => r.json());

// Update a field
await fetch('http://localhost:4185/api/field', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ path: 'hero.title', value: 'New Title' }),
});

// Subscribe to updates
const events = new EventSource('http://localhost:4185/api/events');
events.addEventListener('schema-update', () => {
  // Refetch schema
});

Next Steps

• Learn about the REST API for custom integrations
• Explore Framework Guides for your stack
• Read about the Hosted Platform for managed dashboards