Netlify Docs
Ask Netlify

Contact

Visual editing /Visual Editor /

Local development

Develop and test your Visual Editor site in your local development environment.

Visual Editor supports developing your project's code locally, including the ability to view your running local site inside Visual Editor’s user interface with full visual editing.

This is a powerful way to iterate quickly when developing your site - especially when you're making changes to content models or annotations and want to immediately test these changes in the visual editing environment.

Note that viewing your local site within Visual Editor webapp is optional. You can develop locally with just Next.js, without having to run our tooling for visual editing.

# Prerequisites

  1. Operating system: MacOS, Windows or Linux (the same as Next.js supports).
  2. Node version: v14 or later (which comes packaged with npm v6 or later).
  3. Browser: Google Chrome is currently required. Support for other browsers is planned.

Tip

You may want to use a tool like nvm to run your local site with the best matching Node and NPM versions, while not affecting other installed versions.

# How to use

# Run Next.js locally

Once the project’s repository was transferred to you, the Settings dialog will show you the commands to clone & run the project locally.

The commands shown in the dialog are similar to the below, with the repository URL already filled and for the preview branch - but you can create or pick any other branch to fit your needs.

git clone git@github.com:<user>/<repository-name>
cd <repository-name>
git checkout <branch>
nvm use # Optional - only if you're using nvm!
npm install
npm run dev

At this point, Next.js should be running in dev mode on localhost:3000. Check it out!

You can already make changes to code & content files, and Next.js will refresh the page automatically. Now, let's leave this process running and get your local site displayed within Visual Editor webapp.

# Install & run the CLI

Install the Stackbit CLI for Visual Editor from the terminal:

npm install -g @stackbit/cli

The above command specifies the -g flag to install the package globally and have its executable available everywhere. This may require installing with sudo, depending on your setup (not needed when using nvm).

Run from your local repository's directory:

stackbit dev

or run:

stackbit dev -d <path-to-dir>

Open http://localhost:8090/_stackbit in your browser. This will redirect you straight to Visual Editor editor showing your local site. You can bookmark this URL if you want.

You can now highlight elements, make content changes that will get reflected in your local files, or make code changes locally and see them reflected immediately. That's all there is to it!

Make sure to read things to know.

If something's wrong, jump to troubleshooting tips below.

# How it works

By default, visual editor sites are backed by a remote container managed by us, which is running the site’s preview branch. What you're seeing in the webapp is that container's output, loaded through an code iframe and proxied by our servers to provide the highlighting and editing experience. Everyone working on the same site’s visual editing experience locally work with that container.

In local development mode, the webapp loads the iframe directly from your local proxy (the stackbit dev process). This proxy serves what your local SSG is rendering, but adds a layer on top to support visual highlights, authenticated content changes, and more.

The URL of the page (e.g. https://create.netlify.com/studio/7620acff1hs75ak19ad) is unique to you and is hard-wired to communicate with the stackbit dev process running on your local machine. It will only work correctly when opened on your machine.

# Things to know

Important

There is no association between local development mode and the regular Visual Editor project you've created through the UI. You can use local development to edit any repository that you have cloned locally.

Content editors and other Developers should keep working with the regular project accessible from the dashboard, as usual.

Regular Visual Editor projects always reflect the code in the project's preview branch. When you push code to that branch by whatever means, the webapp will update automatically and changes will be visible to anyone currently working on the project. So make sure to test beforehand.

If you have multiple projects in Visual Editor, you can use local development to work with any of them. To switch between code repositories, stop the stackbit dev process and re-run it from the relevant directory. Note: the shown URL does not change per repository.

Also note the following differences:

  1. When the webapp is in local development mode, the buttons to share & publish are disabled, as these actions are not applicable.
  2. Logs are not shown in the webapp. Check the logs locally (both the web server and stackbit dev emit logs to the terminal).
  3. As mentioned above, you decide whether and when to commit and push, and which code repository and branch to work with.
  4. stackbit dev treats the runnable directory as the directory in which the command was run. You can change this with the --dir (alias: -d) option.

Tip: during development, it's natural to make mistakes when defining models or manually editing content files, which can result in rendering errors and stuff generally not working. It's recommended to regularly run stackbit validate when making such changes to get a verbose check-up of content & models in your code.

# Work with cookies

When working with cookies in your application, they are often set for the domain and port on which your development server is running (e.g. localhost:3000).

Because Visual Editor Dev proxies your dev server through local port 8090, your cookies need to run on localhost:8090. You can achieve this by setting the following cookie:

SameSite=lax

# Troubleshooting tips

If the webapp keeps showing "Connecting to local dev environment" with a loading animation:

This message means that the webapp cannot connect to the local stackbit dev process. Here's what to do:

  1. Make sure stackbit dev is working on your local machine and its log shows no errors.
  2. Make sure you're using Google Chrome as your browser, on that same machine.
  3. If you use multiple user accounts on Visual Editor (this is normally not required, as the same user can be a member of multiple organizations): re-run stackbit dev after logging-in to the desired user, and click the shown URL to open the webapp.

When the connection to stackbit dev is re-established, the webapp should refresh automatically. If nothing of the above works, re-run stackbit dev --log-level debug and share the output with us.

If you're seeing "Failed to connect to your site's local server":

This means that stackbit dev is working, but cannot access your Next's local dev server (launched with npm run dev). This usually happens only when Next.js is down or unresponsive.

  1. Make sure that Next.js is running in its default port (3000).
  2. Look for errors in the Next.js terminal output.
  3. Try to restart Next.js. Hot module reloading in dev mode can sometimes get the server unstable.