Set up visual editor locally

Set up the visual editor locally to customize the visual editing experience.

This doc offers steps on how to set up the visual editor locally for a pre-configured template site, which simplifies the setup process.

The setup process for an existing site will require a lot more customized setup, which you can review in this doc at a high-level.

Different setup path?

There are many ways to set up the visual editor. To find another setup path, check out our docs on choosing the best setup path for you.

Start from a pre-configured template site

To set up the visual editor locally using a pre-configured template:

1. Confirm you have the following first:

   • A Netlify account if you haven’t already signed up
   • Node version: v14 or later (which comes packaged with npm v6 or later).

2. In your terminal, install the Visual Editor CLI globally:

   npm install -g @stackbit/cli

3. Install the Netlify CLI:

   npm install netlify-cli

4. Choose a pre-configured template site to set up. We recommend one of the following visual editing configured site repositories:

   Site repository	Content source	Optimized for
   TypeScript + MUI Starter	Git CMS	- a tutorial-like experience - learning about visual editor capabilities
   ContentOps Starter	Git CMS	- learning about content types with over 35 content types - try more complex content type scenarios
   Auto-annotated portfolio	Git CMS	- learning about auto annotating your site - lots of auto annotated components
   Next.js & Contentful Starter	Headless CMS: Contentful	getting started with Contentful
   Astro & Sanity Starter	Headless CMS: Sanity	getting started with Sanity

What is Git CMS?

For the visual editor, Git CMS refers to storing content in files and managing them directly in those files with Git version control.

5. In your terminal, navigate to where you want your local site directory to live. Next, run netlify sites:create-template TEMPLATE_REPO_NAME, replacing TEMPLATE_REPO_NAME with your template repository name. For example, to use the ContentOps Starter, run:

   $ netlify sites:create-template content-ops-starter

   Follow the site setup prompts, choosing your Netlify team, giving your site a name, and cloning your site repository. You may need to log in to Netlify if you haven’t already. The CLI setup will give you setup links for your site.

    netlify sites:create-template content-ops-starter     ✔
     ? Team: Netlify Testing
     ? Site name (leave blank for a random name; you can change it later): docs-test-
     site-for-visual-editor-setup
   
     Site Created
   
     Admin URL: https://app.netlify.com/sites/YOUR_SITE_NAME
     URL:       [REDACTED]
     Site ID:   [REDACTED]
     Repo URL:  https://github.com/REPO-OWNER/YOUR_SITE_NAME
     ? Do you want to clone the repository? Yes
   
     🚀 Repository cloned successfully. You can find it under the YOUR_SITE_NAME folder

6. Next, in your new local site directory, install visual editor dependencies for your site based on whether the site uses a headless CMS or Git CMS (content stored in files).

   • If your site relies on Git CMS, use npm install -D @stackbit/types @stackbit/cms-git
   • If your site relies on a headless CMS, use npm install -D @stackbit/types @stackbit/contentful, replacing contentful with your headless CMS name.

Dependencies to install

At this time, we have visual editor dependencies to install for these headless CMS options:

• @stackbit/cms-contentful
• @stackbit/cms-contentstack
• @stackbit/cms-datocms
• @stackbit/cms-git
• @stackbit/cms-hygraph
• @stackbit/cms-sanity

7. Run your site’s local development server. Check your site repository README on GitHub for the command to start your local development server. You may also need to install site dependencies with a command like npm install.

   npm run dev

8. In a new terminal window, run the visual editor with the command stackbit dev in your site directory.

   stackbit dev

9. Open the visual editor localhost URL, such as http://localhost:8090/_stackbit.

   

Checkpoint

You should now be able to open the visual editor in local development mode and use the page editor to make changes to your site.

If this is not true for you, please let us know in the Docs feedback form at the bottom of this docs page.

Start from an existing site

The setup process for an existing site will depend on the type of site your setting up and the needs of your team’s visual editing workflow.

In addition to the steps above, you’ll need to:

• Add the visual editor configuration file stackbit.config.ts at the root of your site directory
• Define a content model for your site

For an end-to-end guide that walks through an example of setting up an Astro site locally, check out the Add visual editor to Astro guide that doesn’t use a pre-configured template site.