Dev Server
Many sites support a development mode, where updated and draft content is refreshed instantly without the need for a full rebuild. With Static Site Generators such as Gatsby, this mode is typically the only solution to quickly preview updated content. However, this capability is usually accessible to developers only. Netlify Dev Server makes it easy to run your site in development mode online and provide a live preview for content editors and reviewers in your organization.
You can create dev servers for multiple code branches under a single Netlify site. For each dev server, Netlify provides a stable preview URL that can only be accessed by authenticated users.
Netlify Dev Server can also be used with the Netlify Visual Editor. This provides developers with more configuration and observability to ensure a smooth experience for content editors.
Like with other container technologies, to avoid destabilizing the server, code updates are never pulled into a running dev server instance.
Rather, when you push new code to the branch that a running dev server is using, Netlify starts a new dev server instance in the background. Once that instance is up and healthy, the stable preview URL will automatically switch to proxy the new instance. In the background, the old instance is then automatically stopped.
The feature is free to use for customers in the beta program. After the beta period, usage will be billed based on metered resource usage.
# Prerequisites
Netlify Dev Server runs your site by launching Netlify Dev (netlify dev) in an isolated container, just like you would run it on your own machine. Thus, the steps to prepare the dev server are very similar to those needed to run Netlify Dev locally.
- Confirm that your site can run locally with the Netlify CLI
- Ensure that fresh content is rendered
- Configure environment variables
# Run locally with the CLI
Run your site locally on your machine using netlify dev, and ensure it loads successfully. If you’re new to the CLI, here’s how to get started.
Netlify does its best to auto-detect the web framework you use (if any) and the correct settings, such as the port your development web server listens on. If your site doesn’t load, you may need to adjust some of the automatically-detected settings in your netlify.toml configuration file.
# Ensure that fresh content is rendered
If your site fetches content from a CMS, you may need to adjust your CMS connection parameters in development mode so that it returns updated and unpublished content. Depending on your setup, this may require setting specific development values for use with dev server to avoid impacting production.
For Gatsby, make sure to enable the refresh endpoint while in development mode, to allow sourced content to be reloaded on-demand.
# Configure environment variables
It is very common for sites to read CMS API keys and related connection settings from environment variables. Typically, you’d want to configure different values for these variables based on the context, so that the dev server will use development-specific values instead of production values.
By default, the dev server uses environment variable values set for the Local Development deploy context but you also have the option to set specific values for the Dev Server context. If you’ve already set the appropriate values for local development, chances are you don’t need to define different values for use with dev server.
In the following example, the dev server environment will use the same value for CMS_API_TOKEN as the Netlify CLI on your local machine:
Note that values set for the dev server context can be stored as secrets, as the dev server environment is fully managed by Netlify.
# Enable Netlify Dev Server
Netlify Dev Server is currently in private beta. Contact us to enable Netlify Dev Server for your team.
Once enabled, the
page will be unlocked in the Netlify UI for your sites.# Add a dev server
Once the dev server feature has been enabled for your team, navigate to
and select Add new server. Follow the prompts to select the code branch you want the dev server to pull.
While the dev server is spinning up, you can review the logs to monitor the process:
As the dev server starts up, you can review resource usage metrics (CPU, memory, and disk) that update in near real-time. If a server becomes slow, unresponsive, or crashes during startup or after running for a while, these metrics can come in handy.
The server process is considered live once it starts responding successfully to HEAD requests for the site’s main page (/). At that point, the server state changes from Starting Up to Live.
Once the server is live, you can navigate to the website running on the dev server by selecting the preview URL link. This URL always points to the instance of the dev server that is currently live for that branch.
The preview link is formatted as https://devserver-yourbranchname--yoursitename.netlify.app or https://devserver-yourbranchname.yourcustomdomain.com if you use Netlify DNS. For example, if the branch is staging, it would be https://devserver-staging--yoursitename.netlify.app.
Team members with a Publisher, Content Editor, or Reviewer role can find the preview URL in their dashboard. These users do not have access to manage dev servers.
Selecting the right branch
Typically, reviewers want to preview content changes over a site that’s representative of the latest production codebase. Thus, it’s common to use the main branch (or equivalent) for your dev server but with environment variables set to development values to ensure content updates are visible.
Alternatively, you can create dev servers for another branch, or multiple branches.
However, if your actual need is to share code changes with stakeholders rather than content changes, you should probably use Deploy Previews instead.
# Set up refresh on content updates
If you’re using the visual editor, skip this step
The visual editor has built-in support for updates through content sources.
Most sites that statically generate pages do not have built-in code to automatically track content updates in the CMS and update accordingly.
Supporting automatic updates is a two-step process:
- Your site’s code should provide a dedicated endpoint for triggering content refreshes from the outside. Some frameworks can support this out-of-the-box (as noted below). This does not expose your site to the outside world directly - only authenticated users have access to the content preview in any way.
- In the Netlify UI, generate a webhook URL and add it to your CMS to notify Netlify when content changes.
When the CMS calls the webhook on content updates, the dev server will trigger the refresh endpoint in your site. In this way, only the unique webhook URL is accessible from the outside.
# Add a refresh endpoint to your site
First, your site should support a POST /__refresh endpoint that will trigger a content refresh. Some frameworks provide support for this out-of-the-box in their development mode, under some conditions:
- Gatsby has optional support for the endpoint in development mode. You need enable it and ensure the source plugins you use support it (most of the common ones do).
- Astro has optional support for refreshing the content layer starting with version 5.0. The content layer integrations you use need to support this.
# Add a webhook
Go to
.
Select Add dev server hook and complete the fields to create a hook that will refresh content for the branch your dev server uses:
Select Save to get the hook’s URL:
Copy the hook URL and set-up your CMS (or other source system) to call it on content updates.
For example, here’s how to access webhook settings in Contentful:
You can also manually test your webhook with a curl command:
curl -X POST -d {} https://api.netlify.com/dev_server_hooks/...
# Understand the server lifecycle
At each point in time, there can only be one dev server instance with status Live for a given Netlify site and code branch.
The Live status signifies that the instance is healthy (that is, periodically responds to HEAD / with status 200). The preview URL for the dev server always points to that Live instance.
When a dev server is restarted for any reason (whether manually by user action, or automatically due to new commits made to the branch), here’s what happens:
- A new instance is started in the background, with status Starting up.
- Once that new instance successfully responds to health checks, it becomes Live and the previous instance is set to Stopping and then Stopped.
- If the new instance does not start up successfully in 30 minutes, it is stopped and marked as Failed, and the previous instance remains Live.
A Failed server is not automatically restarted, because that would often result in a restart loop.
However, if a running server that has already reached the Live state stops responding to health checks, or the development server process (that is being run by netlify dev within the dev server instance) crashes, the dev server instance will automatically restart the process without the need for human intervention.
The above logic is meant to offer the least interruption to content reviewers. If a developer has pushed code changes that cause an instance to fail starting up, the preview URL will keep pointing to the healthy instance until the underlying issue is resolved. But if a long-running server simply crashes at some point, content editors will not have to wait for a developer to restart it for them.
You can subscribe to notifications to be informed about such failures.
# Additional configuration
The site configuration allows a few other settings:
You can change the Dev server size and modify the resources allocated to it: CPUs, RAM, and disk. A few presets are available for selection.
After the beta period, billing will be based on the allocated resources, so you should take note to adjust the size to your needs. You can start with a larger instance, and then use the provided resource metrics to monitor actual needs and downsize the server accordingly.
To adjust the command or port that netlify dev uses within dev server, change these values in either the [dev] section of the netlify.toml file for your site or in the Netlify UI under
Note that changing the values in the configuration file will impact local development as well.
# Use with the visual editor
Customers with access to the dev server feature have the option to have the visual editor use it as the underlying web server powering the site, instead of the existing container solution. This has several advantages:
- Unlike the existing container, the dev server supports all Netlify platform primitives with its usage of the Netlify CLI.
- The dev server allows developers to self-serve and monitor resources, access current and historical logs, and adjust resource allocation.
- The dev server has performance optimization, such as caching installed dependencies between restarts.
- As mentioned earlier, the dev server has several extra reliability features: it will never pull code changes to a running container, and will not switch to a newly-started instance until it is deemed healthy.
When the dev server feature reaches general availability (GA), it will become the default container powering the visual editor for everyone.
# Change the editor configuration
To use a dev server with the visual editor, you need to first create a dev server (if you haven’t already).
Then, go to
and select Edit.Switch from Container (Legacy) to Dev server and choose the appropriate branch. Only branches for which there is an live dev server are shown. Then, save your changes.
Once this association is done, a new marking will appear next to the dev server instance that is used by the visual editor:
This serves to let you know that if you make any changes to that server, you may impact the experience of content editors.
# Subscribe to notifications
You can subscribe to receive notifications when certain lifecycle events occur (for example, when a running dev server has failed), by having Netlify trigger external webhooks. You can use these webhooks to receive notifications in Slack or to create some other automated process.
To add a notification:
Go to
.
Create a new HTTP Post request notification. Select the event to receive and the target URL:
Netlify will then trigger your webhook on events, adding further information about the event context in the POST body.
Did you find this doc useful?
Your feedback helps us improve our docs.