The .designjs.json File Format

How DesignJS saves your design locally, what the JSON file contains, and why it’s designed to be committed to your git repository.

Every canvas you work on in DesignJS is saved to a single file: .designjs.json in your project directory. This file is the complete, self-contained representation of your design — the component tree, all styles, and any CSS variables you’ve defined. It’s plain JSON, human-readable, and designed from the start to live in your git repository alongside your application code.

What gets saved

The .designjs.json file contains two top-level sections:

GrapesJS project data — the component tree and all associated styles, serialized by GrapesJS into its standard project format. This includes:

• Every component on the canvas with its tag name, CSS classes, attributes, and text content.
• The full nesting hierarchy (children of children, and so on).
• Per-component CSS rules written through the Style panel or via update_styles.

CSS variables — a flat key-to-value map of any CSS custom properties you’ve set on the canvas root. For example:

{
  "cssVariables": {
    "--brand-primary": "oklch(0.55 0.2 260)",
    "--spacing-section": "4rem"
  }
}

These are saved separately from the component data and reapplied to the iframe’s :root when you reload the canvas.

A minimal example

A canvas with a single <div> containing a heading might produce a file like this:

{
  "assets": [],
  "styles": [
    {
      "selectors": ["#i1a2b3"],
      "style": { "padding": "2rem" }
    }
  ],
  "pages": [
    {
      "component": {
        "type": "wrapper",
        "components": [
          {
            "tagName": "div",
            "attributes": { "id": "i1a2b3" },
            "classes": ["flex", "flex-col", "items-center"],
            "components": [
              {
                "tagName": "h1",
                "classes": ["text-4xl", "font-bold"],
                "components": [{ "type": "textnode", "content": "Hello world" }]
              }
            ]
          }
        ]
      }
    }
  ],
  "cssVariables": {}
}

The format is determined by GrapesJS and is stable across saves — the same canvas will produce structurally identical JSON unless the design changes.

When saves happen

DesignJS writes to .designjs.json in two ways:

Trigger	Behavior
Auto-save	Every 30 seconds while the canvas is open in your browser.
Manual save	Cmd+S on Mac, Ctrl+S on Windows/Linux.

The save status is displayed in the top bar of the editor (Saving…, Saved, or an error message if the write fails). Both triggers overwrite the file completely — there is no incremental patch format.

Auto-save runs on a 30-second interval from when the canvas finishes loading. If you close the browser tab before 30 seconds have elapsed since your last change, use Cmd+S to save manually first.

Reload and restore

When you reload the canvas (or reopen the browser tab), DesignJS reads .designjs.json at startup and reconstructs the exact state it was in when last saved:

1. The GrapesJS project data is loaded, restoring the full component tree.
2. The cssVariables map is reapplied to the iframe :root.

If the file doesn’t exist yet (a fresh project), the canvas starts empty. If the file exists but is malformed JSON, the canvas logs a warning and starts empty rather than crashing.

Committing to git

The .designjs.json file is designed to be committed. Because it’s plain JSON with a stable structure, git can diff it meaningfully:

git add .designjs.json
git commit -m "design: add hero section with brand colors"

In a pull request review, your teammates can see exactly which components changed, which classes were added, and which CSS variables were modified. This gives design changes the same review workflow as code changes.

Add .designjs.json to your project’s tracked files from the start. It’s the single source of truth for your canvas state — treat it like any other source file.

What is not saved

The file does not contain:

• Selection state — whatever is selected in the editor is not persisted. After a reload, nothing is selected by default.
• Editor UI state — panel sizes, scroll positions, and zoom level are not saved.
• Assets — the assets array in the GrapesJS project data is present but image uploads are not yet supported in v0.1. External image URLs referenced in your HTML are preserved as-is.

CSS variables via the agent

If your agent calls set_variables, the changes are saved to .designjs.json under the cssVariables key at the next auto-save or manual save. The variables take effect immediately in the iframe without a save, but they won’t survive a reload until the file is written. To force an immediate save from the editor, press Cmd+S after the agent updates variables.