Troubleshooting

A region isn't editable

The compiler only tags content it can confidently identify. If a node is missing from the overlay:

Confirm the file is inside your include globs and not excluded as site chrome.
Re-run npx nexus generate after structural changes — the schema is built at compile time, not at runtime.
Loose text directly inside a parent (e.g. Build normally.<br/>Manage visually.) is wrapped automatically; deeply nested mixed content may need a small refactor or an explicit wrapper element.

Stacked/overlapping elements (like a spotlight image behind another) are all tagged — click again to cycle selection through the stack.

Site chrome shows collection controls

Navigation and footer links rendered with .map() can be mistaken for editable collections. Exclude site chrome so it stays clickable and untouched:

nexus.config.ts

export default defineConfig({
  exclude: ["components/site/"],
});

Path matching is normalized across operating systems, so use forward slashes even on Windows.

Edits disappear after reload

This usually means the override never persisted. The in-memory adapter is for demos only — swap it for the HTTP adapter (or your own) so changes survive:

import { createHttpAdapter } from "@nexus-cms/react/adapters";

const adapter = createHttpAdapter({ baseUrl: process.env.NEXT_PUBLIC_CMS_URL! });

Revert deletes the stored override. Make sure your adapter implements deleteOverride (the bundled memory and HTTP adapters do); without it, reverting falls back to writing an empty override, which some stores merge instead of removing.

`TS7016: Could not find a declaration file for '@nexus-cms/core'`

A monorepo dts ordering race. Ensure dependent packages build their types first — in Turborepo, make the dev task depend on ^build:

turbo.json

{
  "tasks": {
    "dev": { "dependsOn": ["^build"], "cache": false, "persistent": true }
  }
}

Links still navigate in edit mode

In edit mode Nexus locks underlying navigation so clicks select regions instead of following links. Only the editor's own toolbar and elements marked nav[data-nexus-nav] (or a top-level <header>) stay interactive.