Local Development

Netlify Create supports developing your project's code locally, including the ability to view your running local site inside Netlify Create'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 the Netlify Create webapp is optional. You can develop locally with just Next.js, without having to run our tooling for visual editing.

The online code editor vs. local development#

We also provide a built-in code editor within our user interface. What's the difference?

• The online code editor is useful when you don't have access to a local development environment, or need to make small tweaks without the hassle to set that environment up.
• The online code editor commits all changes to the project's preview branch immediately. Thus, it's less suitable for changing code while other content editors or developers are also working on the project.
• With local development you have full control over which branch you're working on. Nothing gets committed automatically, and you decide whether and when to commit any changes. You can use your preferred development lifecycle and branching strategy.
• With local development, you have full visibility over the local filesystem and the running SSG process. If something breaks, you can easily restart, cleanup temporary files, and so on.
• Pages show up faster and edits finish quicker, as you're working mostly with localhost with minimal network latency.

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.

How to use#

Running Next.js locally#

Once the project's repository was transferred to you, the Project 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 the Netlify Create webapp.

Installing & running the CLI#

Install the Stackbit CLI for Netlify Create 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 the Netlify Create 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 below.

How it works#

By default, Netlify Create projects are backed by a remote container managed by us, which is running Next.js over the project'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 project 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#

Regular Netlify Create 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 Netlify Create, 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. The online code editor is not available, as the webapp is agnostic in this mode to what repository your'e running on locally.
3. Logs are not shown in the webapp. Check the logs locally (both the web server and stackbit dev emit logs to the terminal).
4. As mentioned above, you decide whether and when to commit and push, and which code repository and branch to work with.
5. 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.

Working 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 Netlify Create 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#

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 Netlify Create (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.