Oleg Isonen
bc7e58af84
## Problem A fresh iterative Preview can lose its rendered content on the first client navigation with a React `useContext` error. MCP issue reports can also miss the page or instance ID needed to locate a problem, and concurrent tool calls can overwrite newer report context with an older snapshot. ## Fix - Have Vite scan generated routes before the first navigation. This applies to the base React Router template and the Netlify and Cloudflare overlays. It changes local iterative Preview, not saved project data or production routing. - Include up to three recent, validated tool targets in MCP issue reports. A project-relative screenshot path is matched to its page ID; the CLI does not store the path, full URL, token, or page content. It cannot read the Builder's current UI selection, but includes an instance ID when a tool call names one. - Treat structured MCP error results as failures and serialize report-state writes within a CLI session, so a concurrent older write cannot replace a newer result. The reporting work from #6574 is now included here. #6574 is superseded. ## Verification - Reproduced #6569 twice with CLI 0.306.0 and a cold optimizer cache. With the Vite change, a cold `/` → `/blog` navigation and direct article load rendered without browser errors. - The config assertion failed without the Vite entry and passed with it. A proposed optimizer test also passed without the fix, so it was removed; the real cold-navigation check remains the behavioral evidence. - The new concurrent-write test passed with serialization and failed when the queue was temporarily removed. All 106 focused CLI tests, CLI typecheck, root lint, formatting, and generated API check passed on the combined branch. - Earlier checks of the same Preview and reporting code passed: 133 prebuild tests, 144 project-build MCP tests, protocol and Builder reporting tests, affected typechecks, CLI build, generated docs, and CI on the separate PRs. - The fixture build passed without changing tracked files. The full local fixture pipeline stopped at sync because the development server returned bundle version `bundle-17o6sch` while this checkout expects `bundle-1sh9iaz`. The combined commit passed Linux and Windows fixture checks and all other required CI jobs. - Full Luna/low agent evaluations were run earlier on the combined branch: the latest run passed 8 of 9 fixture tasks, while the managed-form assertion failed on an unrelated task. Saved baselines were missing or incompatible, so the command failed overall. No baselines changed. Evaluations were not rerun for this final concurrent-write change. ## Checklist - [x] Reproduce and fix the first-navigation Preview failure - [x] Cover the base, Netlify, and Cloudflare templates and generated fixtures - [x] Include safe recent page and instance IDs in MCP issue reports - [x] Treat structured MCP errors as failures - [x] Serialize concurrent report-state writes and verify the regression test fails without the queue - [x] Review documentation impact: Preview usage and user guidance are unchanged; no docs change - [x] Run focused local checks and attempt the fixture pipeline - [x] Confirm required CI passes on the final combined commit Closes #6569 Ref #6571
Webstudio CLI
The Webstudio CLI helps you to link, sync and build projects from Webstudio Cloud. This README will guide you through the process of setting up a Webstudio project on your local machine and continually sync it with the cloud.
Prerequisites: Installing Node.js
You need Node.js to use the Webstudio CLI. If Node.js is already installed in your system, you can skip ahead to the section on installing the Webstudio CLI.
To install Node.js using NVM, first install NVM by running:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
Once NVM is installed, you can install Node.js version 22 by running:
nvm install 22
Verify your Node.js installation by checking its version:
node --version
Installing the Webstudio CLI
To get started with the Webstudio CLI:
-
Download and install the CLI using the following command:
npm install -g webstudio@latest -
Confirm the installation by checking the CLI version:
webstudio --version -
To keep your CLI updated, use the same command used for installation whenever a new release is available.
Initiating a Webstudio Project
Now, you can run a Webstudio project on your local machine using this command:
webstudio
This will initiate the flow to connect your Webstudio Cloud project and build it in your local computer. The default flow will guide you through the steps. You can also perform all the operations individually using independent commands.
Commands
Here is the list of independent commands:
- version
- help
- link
- sync
- build
link
The link command stores access to a Webstudio Cloud project. MCP clients use that connection to read and edit the latest Builder build directly; the project does not need to be published or synchronized first.
Shell-capable agents can call MCP tools directly as CLI subcommands immediately after linking. This does not require MCP client configuration or a client restart:
webstudio meta.index
webstudio components.search '{"brief":"button"}'
webstudio insert-fragment --input-file .temp/insert-fragment.json --dry-run
.temp/insert-fragment.json:
{
"parentInstanceId": "<parent-id>",
"fragment": "<section />"
}
The explicit equivalent is webstudio mcp single-op-call <tool> '<json>'.
Use webstudio connect <client> only when you want persistent native MCP tools
inside Claude Code, Codex, Cursor, or VS Code. A persistent client may need to
reconnect after its configuration or cached tool catalog changes.
See the Webstudio MCP documentation for setup, discovery, editing, verification, and safety guidance.
You can link a project from Webstudio Cloud with the following command:
webstudio link
This command will prompt you to paste a link which you can create using the Share option in your project.
Make sure to provide Build access when generating the link in Webstudio Cloud.
sync
Once the project is linked, use the sync command to sync it with the cloud:
webstudio sync
Sync downloads the current saved Builder project and its asset files, then prepares the local content index. Publishing is not required.
Use the export with webstudio build or webstudio import --to "<target-share-link>". Sync is not required for MCP editing.
build
Now, you can build your project with the build command:
webstudio build
During this phase, the CLI establishes the necessary routes and pages, scaffolding the entire application using the default Remix template. Additionally, all assets, such as images and fonts are downloaded to the assets folder inside the public directory.
Once the project is scaffolded, you can run npm install and then npm run dev to run your app in development mode.
If you want to build a production version of the app, you can run npm run build.
Deployment
Vercel
Once you've built the project locally, you can use the Vercel CLI to deploy your project directly to Vercel:
vercel deploy
Follow the instructions here to install the vercel CLI. We plan to add more deployment targets in future.
Netlify
If you want to deploy to netlify, you can use Netlify CLI to deploy your project directly to Netlify:
netlify deploy
You can configure the project to support netlify serverless/edge-functions respectively, as deployment target at the time of initially setting up your project. Please check the initiating-a-webstudio-project section.
You can manually change it using the build command. For serverless functions:
webstudio build --template netlify
Important Notes
If you use vercel build before vercel deploy, make sure to clean your app folder in the project afterward.
Vercel injects a few files to support and deploy Remix using their CLI, but these files are not necessary for your project when you use it locally.