> ## Documentation Index
> Fetch the complete documentation index at: https://opencanvas.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.

<Note>
  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.
</Note>

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

```bash theme={null}
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.

<Tip>
  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.
</Tip>

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