Preview Setup

When building a static site, you normally run a development server that watches your local files and hot‑reloads the page when something changes. LeadCMS extends this idea by watching for changes in the CMS itself, so that editors and developers can see updates without rebuilding the site.

In this section you will learn how to set up a live preview server using the LeadCMS SDK. We’ll cover how the leadcms watch command subscribes to real‑time updates, how to configure a multi‑service preview container, and how to register preview URLs in the CMS.

How live preview works

When you run your project in development mode (e.g. next dev for Next.js or astro dev for Astro), the framework watches for local file changes and refreshes the page. However, updates made in the CMS aren’t automatically reflected locally unless you synchronise them. The LeadCMS SDK solves this with the watch command:

It connects to the CMS’s Server‑Sent Events (SSE) endpoint.
It listens for events such as content‑updated, draft‑updated and live‑preview updates.
Upon receiving an event, it downloads the affected content and writes the updated MDX/JSON files to your local .leadcms/content directory.
For temp user previews, it creates a new file named {slug}-{userUid}.mdx (or .json) with draft: true in the frontmatter. These temporary files enable per‑user live editing.

The watcher logic is implemented in the SDK’s SSE watcher script【152248343170964†L37-L205】【152248343170964†L206-L324】. This script automatically reconnects on errors and respects your environment configuration. You don’t need to write any code yourself; you simply run leadcms watch.

Setting up a preview server with Docker

Although you can run the watch command manually on your machine, the simplest way to preview edits from the CMS is to use the preview Docker setup generated by the SDK. When you run leadcms docker, it creates a preview/ folder in your project with a Dockerfile, nginx configuration and supervisord config.

Inside the generated preview/Dockerfile you’ll see that it:

Uses Node 20 on Alpine and installs nginx and supervisor for multi‑service management.
Accepts build arguments for LEADCMS_URL, LEADCMS_API_KEY and LEADCMS_DEFAULT_LANGUAGE and exports them as environment variables【71477882830231†L27-L35】.
Installs your project dependencies (using npm or pnpm) and copies your code into the container【808081300895072†L27-L45】.
Copies the preview/nginx.conf and preview/supervisord.conf files, which configure the reverse proxy and run multiple processes.
Creates a start.sh script that fetches initial content using leadcms pull and then starts supervisor【808081300895072†L56-L65】.

The nginx.conf proxies all HTTP and WebSocket requests to your development server on port 3000. It enables hot reload for frameworks like Next.js and Astro and sets CORS headers for cross‑origin requests【594655418659028†L28-L43】【594655418659028†L78-L100】. The supervisord.conf starts three services: the dev server (npm run livepreview), nginx, and the LeadCMS SSE watcher (npx leadcms watch)【262007605042821†L6-L33】【262007605042821†L47-L63】.

To build and run your preview server:

Generate preview files with leadcms docker

# From your project root
pnpm exec leadcms docker

This command creates a preview/ folder with a Dockerfile and configuration files. You can customise the Dockerfile if needed.

Build the preview image

# Build the preview image
docker build -f preview/Dockerfile -t my-site-preview .

Run the preview container

# Replace values with your CMS URL and API key
docker run -p 80:80 \
  -e LEADCMS_URL=https://cms.example.com \
  -e LEADCMS_API_KEY=<your-api-key> \
  -e LEADCMS_DEFAULT_LANGUAGE=en \
  my-site-preview

The preview server runs on port 80 and proxies requests to your dev server on port 3000. If you need to use a different port, adjust the EXPOSE and docker run parameters.

Once the container is running, open http://localhost in your browser. As you edit content in LeadCMS, the watcher will save updated files into your project and your dev server will hot reload the changes automatically.

Configuring preview URLs in LeadCMS

To enable live preview links in the LeadCMS admin UI, navigate to Settings → Preview and fill in the Preview URL Template and Live Preview URL Template fields. These templates define how the CMS constructs preview links for published content and live draft previews. You can use the following variables:

{lang} – language code (e.g. en, es)
{slug} – the content slug (e.g. about-us)
{userId} – the ID of the user editing the content
{lang+slug} – language code combined with slug

For example:

https://preview.example.com/{lang+slug}/ – general preview link for a published or draft page.
https://preview.example.com/{lang+slug}-{userId}/ – user‑specific live preview link for unsaved edits.

In the LeadCMS admin settings you will see helpful descriptions and example templates:

Preview settings

After saving your settings, editors can click Preview or Live Preview buttons in the CMS to open the correct URL on the preview server.

Summary

LeadCMS live preview combines your framework's dev server with a simple SSE watcher and reverse proxy. By running the watch command (via Docker or directly on your machine) you can see published, draft and live editor changes instantly. Make sure to set up your preview URL templates in LeadCMS and provide the required environment variables (LEADCMS_URL, LEADCMS_API_KEY, LEADCMS_DEFAULT_LANGUAGE) to your preview server.

Next steps

With your preview server configured, learn how to handle drafts and explore advanced preview features:

Draft Preview

Handle draft content and preview modes in your application

Live Preview

Understand the future vision for simplified live preview