config.json

.design/config.json describes one design folder: its schema version, component providers, viewports, board organization, code generation, and host applications. It is validated when Velloo loads the folder.

Minimal shape

{
  "schemaVersion": 4,
  "toolVersion": "<installed version>",
  "name": "product",
  "libraries": {
    "app": {
      "id": "shadcn-upstream",
      "version": "<resolved version>",
      "source": "in-repo",
      "componentsPath": "../src/components/ui"
    }
  },
  "defaultLibrary": "app",
  "viewportPresets": [
    { "name": "Desktop", "w": 1440, "h": 900 }
  ]
}

Let velloo init write real version and path values. The supported provider ids are shadcn-upstream, none, mui, antd, and chakra; a library source is binary, cache, or in-repo.

What belongs here

Area	Fields	Purpose
Identity	schemaVersion, toolVersion, name, folderId	Format gate, writing version, design name, and optional stable cloud identity
Providers	libraries, defaultLibrary	Named provider entries and the fallback used by screens
Canvas	viewportPresets, defaultScreen, defaultBoard	Initial focus and useful viewport sizes
Board organization	boardOrder, boardGroups	Sidebar order and higher-level areas of work
App output	codegen, styling	Component locations/aliases and the CSS channel
Host integration	hostApp, hostApps, extensions	Resolve app-specific components in one app or a monorepo

defaultLibrary must name a key in libraries. Screens can select another registered key. codegen.componentsDir records where the app’s UI components live; codegen.componentsAlias preserves the import prefix used in emitted code.

hostApp covers a typical single application. hostApps names several roots in a monorepo; an extension can select the app whose imports and dependencies it needs.

Repository components

A host app entry carries two optional fields governing repository components:

"hostApp": {
  "root": "../apps/web",
  "preview": "preview.web.tsx",
  "components": {
    "include": ["src/design-system"],
    "exclude": ["src/components/internal"]
  }
}

• preview points at the preview entry, resolved from the design folder root. Omit it and Velloo looks for preview.{tsx,jsx,ts,js} in the design folder (preview.<appKey>.* for a named host app), then a built-in framework recipe, then no wrapper at all. You rarely set this by hand: set_preview_entry writes the conventional filename.
• components.include / components.exclude bound discovery beyond what the app’s entries and routes import. include adds component roots — files or directories, relative to the host root — for a design system the routes don’t reach yet; exclude drops matching specifiers or paths. Both are optional, and a folder normally needs neither.

The required name is the design’s identity in the CLI, canvas title, and agent session. It lives with the design so it survives a move. For a design outside the repository, an app:<relative-path> value resolves from the application root recorded in its machine-local binding.

What does not belong here

Repo-wide design discovery lives in velloo.json at the repository root. It lists in-repository design paths and may select a default by name:

{
  "$schema": "<optional schema URL>",
  "designs": ["design/product", "design/marketing"],
  "defaultDesign": "product",
  "feedback": { "enabled": true }
}

Every entry is a path to a design inside the repository; an entry pointing outside it is refused, because a repository you cloned must not be able to aim Velloo elsewhere. defaultDesign must match the name in one listed design’s .design/config.json. The pre-v4 projects / defaultProject shape is read for migration and rewritten by velloo upgrade.

A design kept outside the repository, whether in Velloo-managed storage (velloo init --external) or a directory you chose, never appears here. It is recorded only on your machine under ~/.velloo/designs/.locations/, and commands run inside the checkout see it alongside the velloo.json designs. Use velloo design bind <design folder> to attach one to a moved or cloned checkout. An older { "managed": … } entry is refused with the same instruction: remove it, then bind the folder.

feedback.enabled is the repo-level decision about whether the send_feedback tool exists; personal contact consent stays on the machine in ~/.velloo. Older folder-level feedback fields can still be read during migration but should not be copied into new configs.

Editing guidance

Use velloo design add, the canvas, or MCP lifecycle operations for routine changes. Hand-edit the file only when you understand the relationship being changed, then run velloo run so validation fails close to the edit. velloo status only lists running canvases and cloud sign-in; it does not validate config.