Skip to content

Document preview base url setting for live preview #835

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
robluton wants to merge 2 commits into
base: main
Choose a base branch
from
+45 −1
Open

Document preview base url setting for live preview #835

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3a3022b
preview base url docs
robluton Sep 25, 2026
d658591
add note about the trailing slash
robluton Sep 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions content/guides/01.data-model/1.collections.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,8 @@ Live preview is used on the [item page](/guides/content/editor) and allows for y

Use item field values to construct the live preview URL, including unique identifiers and the content version, so you can preview draft content before publishing it.

Start the URL with the `{{$preview_base_url}}` variable to take the host from the [Preview Base URL](/guides/content/live-preview#set-a-preview-base-url) project setting instead of the schema. Each environment can then use its own host.

::callout{icon="i-lucide-graduation-cap" color="secondary" to="/guides/content/live-preview"}
Read the Live Preview guide.
::
Expand Down
44 changes: 43 additions & 1 deletion content/guides/02.content/5.live-preview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,49 @@ For more information, see the [Live Preview Reference Tutorials](#reference-tuto
Navigate to Settings -> Data Model and select the collection you wish to configure. In the "Preview URL" section, specify the Preview URL for your project by selecting the field you wish to use to identify your object in your application from the dropdown and entering a URL in this format:
`http://your-website-url/<field>`

### Using Live Preview with Your Application
If your project runs on more than one environment, use a [Preview Base URL](#set-a-preview-base-url) instead of a hardcoded host.

## Set a Preview Base URL

The Preview URL is part of your collection's configuration, so it is included in schema snapshots. If the URL contains a hardcoded host, promoting the schema from development to staging to production copies that host into every environment.

The **Preview Base URL** project setting solves this. You store only the path in the collection's Preview URL, and each Directus instance supplies its own host.

1. Navigate to **Settings** > **Project** and find the **Live Preview** section.
2. Enter your website's base URL in **Preview Base URL**, for example `https://staging.example.com`, and save. A trailing slash is ignored.
3. Navigate to **Settings** > **Data Model** and select your collection.
4. In the **Preview URL** field, select **Preview Base URL** from the variable dropdown, or type `{{$preview_base_url}}`.
5. Add the rest of the path after the variable, for example `{{$preview_base_url}}/blog/{{slug}}`.

When you open the preview, Directus replaces `{{$preview_base_url}}` with the value from project settings. With the example above, the item with the slug `my-post` previews at `https://staging.example.com/blog/my-post`.

You can combine the variable with others, such as `{{$version}}`:

```text
{{$preview_base_url}}/blog/{{slug}}?preview=true&version={{$version}}
```

::callout{icon="i-lucide-info"}
**Variable Dropdown**
The **Preview Base URL** variable only appears in the Preview URL dropdown after you save a value in project settings.
::

### Use Live Preview Across Environments

Now that the host lives in project settings, you can promote the same schema to every environment:

1. On each Directus instance (for example development, staging, and production), set **Preview Base URL** to that environment's website URL.
2. Configure the collection's Preview URL once, using `{{$preview_base_url}}` followed by the path.
3. Promote the schema with the [Schema API](/api/schema) or [Environment Sync](/guides/environment-sync). The Preview URL carries only the path, so each instance resolves it against its own base URL.

Each environment still needs its own `CONTENT_SECURITY_POLICY_DIRECTIVES__FRAME_SRC` value that matches its base URL, as described in the [pre-requisites](#live-preview-pre-requisites).

::callout{icon="i-lucide-triangle-alert" color="warning"}
**Environment Sync and Project Settings**
Environment Sync includes the `settings` resource by default, and `preview_base_url` is part of that record. Pushing settings overwrites the target's Preview Base URL with the source's value. Exclude settings with `--no-settings`, or set the value again on the target after pushing. See [Configuration resources](/guides/environment-sync/reference#configuration-resources).
::

## Using Live Preview with Your Application

Once configured, Directus will send a request to your application for a page with the specified URL format. For example, if you've configured the URL to be `https://mysite.com/posts/{id}`, and load the preview for the item with an `id` of `42`, then your application will receive a request to `https://mysite.com/posts/42`. You may choose to add `preview=true` to indicate to your client that it needs to treat this as a live preview. You may also choose to add an access token with the ability to view items as an additional URL query parameter.

Expand Down
Loading