0 Fork 0

mirror of https://github.com/webstudio-is/webstudio.git synced 2026-11-09 22:14:29 +09:00

Files

T

Oleg Isonen e4983b0d1d fix: Report unsupported Node versions (#6058 )

Closes #6057

## Outcome

Generated projects now reject Node.js versions older than 22.12 before
React Router, Remix, or Vite evaluates SDK components. Users see the
package-manager engine error with the current and required versions
instead of the indirect `sanitize-html` / `htmlparser2`
`ERR_REQUIRE_ESM` stack trace.

## Root cause

`sanitize-html@2.17.6` synchronously loads the ESM-only
`htmlparser2@12`. That dependency combination relies on synchronous
`require(ESM)` support, which Node.js enabled by default in 22.12.
Generated projects incorrectly declared the broader `>=22` range,
allowing an unsupported runtime to reach SSR evaluation.

## Implementation

- Set the CLI and all generated base templates to `engines.node:
>=22.12.0`.
- Add npm `devEngines.runtime` with `onFail: error`, which runs before
install, CI, and run commands.
- Enable `engine-strict` in generated npm configuration so pnpm also
rejects an unsupported runtime.
- Regenerate every tracked CLI fixture package manifest.
- Update CLI documentation and the release-smoke manifest contract.
- Remove the earlier sanitizer-bundling workaround from the branch;
sanitizer code and packaging are unchanged from `main`.

## Checklist

- [x] Declare the exact Node.js compatibility floor
- [x] Fail before generated development, build, and start commands
- [x] Cover the generated engine contract with a fail/pass regression
- [x] Regenerate and inspect all affected fixtures
- [x] Review documentation impact and update the CLI guide
- [x] Keep sanitizer behavior and SDK packaging unchanged

## Verification

- Regression demonstrated failing before the template metadata change
and passing afterward
- `pnpm --filter webstudio test` — 946 passed
- `pnpm --filter webstudio typecheck`
- `pnpm --filter webstudio build`
- `pnpm fixtures`
- `pnpm lint`
- `pnpm exec oxfmt --check` on changed source, template, fixture, and
documentation files
- `git diff --check`

Agent evaluations were not run because they require separate approval.

2026-08-09 01:53:31 +02:00

7.9 KiB

Raw Permalink Blame History

description

description
Webstudio's Command Line Interface (CLI) allows you to interact directly with your Projects from the command line.

⬛ CLI

Webstudio's CLI lets you work with Projects from the command line. You can export and build a Project, publish and manage domains, inspect Project permissions, capture screenshots, and expose the configured Project to automation tools through MCP.

For self-hosting, the CLI can export your entire Webstudio Project. Once exported, these projects are ready to be deployed on any hosting platform of your choice - giving you complete freedom over where and how your website goes live.

Quick setup

The current Webstudio CLI package is webstudio. Run it with npx; do not install it globally or create a permanent webstudio command unless you intentionally need that. Do not use the old @webstudio-is/cli package or the old wstd command.

Use this page as the source of truth for the CLI package. Do not infer the package name or command from local repositories, old README files, or older examples.

First, check whether Node.js and npm are already installed:

node --version
npm --version

If node is version 22.12 or greater and npm prints a version, skip Node.js installation. If either command is missing, install Node.js 22.12 or greater before using the Webstudio CLI.

Run the latest Webstudio CLI without a global install:

npx --yes webstudio@latest --version

No separate Webstudio CLI installation is required when using npx. After verifying the latest CLI with npx --yes webstudio@latest, you can use the shorter npx webstudio command in the same environment.

For the latest version regardless of any existing global install, use npx --yes webstudio@latest.

How to run Webstudio commands

Examples on this page use the no-install npx webstudio command:

npx webstudio <command> [options]

Use one of these command formats:

Setup	Command format
Latest one-off run, all OSs	`npx --yes webstudio@latest <command> [options]`
After verifying latest	`npx webstudio <command> [options]`

Running with npx does not install a permanent webstudio command. Continue using npx webstudio for normal usage.

Use npx webstudio --help for the current command list.

How to update the CLI

The recommended npx setup does not install a permanent copy of the Webstudio CLI, so there is no separate update command. Run the latest published version explicitly:

npx --yes webstudio@latest --version

Then use @latest with any command when you need to guarantee that run uses the newest release:

npx --yes webstudio@latest <command> [options]

This updates the CLI used by npx; it does not modify your linked Project or its .webstudio files until you run a command that does so. If you previously installed webstudio globally, remove that installation to avoid invoking an older permanent command:

npm uninstall --global webstudio

First use

To use the CLI with a Project, you need an existing Webstudio Project and a Builder share link with Build access. Create the share link from the Share dialog in the Builder.

Run the guided flow:

npx webstudio

Or link a Project non-interactively:

npx webstudio link --link "<share-link-with-build-access>"

Publish the Project in Webstudio Cloud before syncing when you need recent Builder changes in the local export.

Install Node.js only when needed

You need Node.js 22.12 or greater to use the Webstudio CLI. If node --version reports version 22.12 or greater, skip this section.

On macOS or Linux, you can install Node.js with NVM. First check whether NVM already exists:

command -v nvm

If nvm is not found, install it:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash

After installing NVM, restart your terminal. If nvm is still not found, source your shell profile and try again.

Once NVM is installed, you can install Node.js version 22 or greater by running:

nvm install 22

Verify your Node.js installation by checking its version:

node --version

On Windows, install Node.js 22.12 or greater from nodejs.org or use a Windows-compatible Node version manager. After installing Node.js, open a new terminal and verify:

node --version
npm --version

How the CLI connects to a Project

Most CLI commands operate on the single Project configured in the current directory.

.webstudio/config.json stores the Project ID.
The global Webstudio config stores the origin and share-link token.
npx webstudio sync downloads the Project bundle to .webstudio/data.json.
Synced asset files are stored in .webstudio/assets.

You can configure a Project interactively:

npx webstudio link

Or pass a share link directly:

npx webstudio link --link "<share-link>"

For automation, use init with JSON output:

npx webstudio init --link "<share-link>" --json

The share link should include Build access when you need to sync, build, import, or automate Project changes.

Export and build a Project

After linking, publish the Project in Webstudio Cloud, then sync it locally:

npx webstudio sync

Build a dynamic app with a deployment template:

npx webstudio build --template docker

{% hint style="info" %} See export types for more information about JavaScript applications vs. static sites. {% endhint %}

The CLI scaffolds the application, creates its routes and pages, and downloads assets. In the generated project, install dependencies and use the scripts in its package.json to develop or create a production build.

Build a static site with:

npx webstudio build --template ssg

Please review the limitations of using the static site export instead of dynamic templates.

Other workflows

The CLI can also:

Import a synced Project into another Project.
Preview an export and capture screenshots.
Publish, unpublish, and inspect publishing jobs.
Manage and verify custom domains.
Audit accessibility, security, SEO, and performance settings.
Expose a Project to AI agents and other automation through MCP.

Use the built-in help for current commands and options:

npx webstudio --help
npx webstudio <command> --help

Automation and MCP

Webstudio MCP lets agents inspect and edit the native visual-builder model so their changes remain editable in the Builder. After linking a Project, shell-capable agents can call MCP tools directly without configuring or restarting an MCP client:

npx webstudio meta.index
npx webstudio insert-fragment '{"parentInstanceId":"<parent-id>","fragment":"<ws.element ws:tag=\"section\" />"}' --dry-run

The explicit equivalent is npx webstudio mcp single-op-call <tool> '<json>'. To keep Webstudio tools available inside a supported client, generate its persistent configuration:

npx webstudio connect claude
npx webstudio connect codex
npx webstudio connect cursor
npx webstudio connect vscode

See Webstudio MCP for the exhaustive, versioned setup, discovery, editing, verification, safety, and troubleshooting reference generated from the latest published CLI manual.

Webstudio MCP – Connect agents to the native visual-builder model
Download – Export a static site directly from the Builder
Netlify – Deploy your project to Netlify
Vercel – Deploy your project to Vercel
VPS with Docker – Deploy to your own server using Docker
Publishing and custom domains – Set up custom domains for your site

7.9 KiB Raw Permalink Blame History Unescape Escape