Reference

Security & privacy

nextcanvas writes files on your disk in response to clicks in a browser. That is exactly the kind of power a stray web page would love to borrow, so the write-back server is locked to your own machine and your own project. Here is what that means and how to loosen it when your setup needs it.

It only runs in development

Everything is gated on NODE_ENV === 'development'. A production build stamps no source locations, serves no overlay script, and never starts the write-back server. There is nothing to disable before you deploy.

The write-back server stays on your machine

In next dev, withCanvas starts a small HTTP server (port 3131) that applies edits to source files. It is bound to loopback only, so the LAN cannot reach it, and every write request passes three gates before a byte is written:

Gate	What it stops
Origin check	Only requests from a local origin (`localhost`, `127.0.0.1`, `::1`, a private LAN address) are accepted. A random site open in the same browser cannot POST an edit — its `Origin` is rejected, and it never receives a CORS grant, so it cannot even read the response.
Host check	Defeats DNS rebinding, where a hostile domain resolves to `127.0.0.1` so the browser treats the edit server as same-origin. A request arriving under a non-local `Host` header is refused.
Path containment	Every file to edit must resolve — symlinks followed — to a real source file inside your project root. No `..` escapes, no symlink out of the tree, no `node_modules`, no `.d.ts`, and only source extensions (`.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`).

No account, no telemetry. nextcanvas talks only to its own localhost server. Nothing about your code or your edits leaves your machine.

When you develop through a forwarded domain

Codespaces, Gitpod, a remote dev box, or a custom *.dev host serve your app from an origin that is not localhost. Grant those origins explicitly:

NEXTCANVAS_ALLOWED_ORIGINS=https://your-app.github.dev next dev

The value is a comma-separated list of exact origins. Each granted origin is also accepted as a Host, since the forwarded request arrives through that same domain.

Environment variables

Variable	Default	Purpose
`NEXTCANVAS_PORT`	`3131`	Port for the write-back server. The same value is inlined for the browser overlay.
`NEXTCANVAS_ALLOWED_ORIGINS`	—	Comma-separated origins allowed in addition to local ones — for forwarded/remote dev.
`NEXTCANVAS_HOST`	`127.0.0.1`	Bind address. Set to `0.0.0.0` to test from a phone on your LAN — the origin/host checks still apply.
`NEXTCANVAS_ROOT`	enclosing git repo	The directory edits must stay inside. Defaults to the git root (so a monorepo's shared components resolve), falling back to the dev server's working directory.

If an edit is refused

A refused edit shows a toast with the reason. The common cases: “origin not allowed” means you are serving from a non-local domain — add it to NEXTCANVAS_ALLOWED_ORIGINS; “outside the project root” means the file lives beyond NEXTCANVAS_ROOT — widen the root if that is genuinely your source.