Web Previews DatoCMS plugin

This plugin adds side-by-side previews, and quick links in the record sidebar to preview your webpages.

🚨 Important: This is not a drag & drop plugin! It requires a lambda function on your frontend website(s) in order to function. Read more in the following sections!

Installation and configuration

Once the plugin is installed you need to specify:

• A list of frontends. Each frontend specifies a name and a preview webhook, which will be called as soon as the plugin is loaded. Read more about it on the next chapter.
• Sidebar open: to specify whether you want the sidebar panel to be opened by default.

⚠️ For side-by-side previews to work, if your website implements a Content Security Policy frame-ancestors directive, you need to add https://plugins-cdn.datocms.com to your list of allowed sources, ie.:

Content-Security-Policy: frame-ancestors 'self' https://plugins-cdn.datocms.com;

The Previews webhook

Each frontend must implement a CORS-ready JSON endpoint that, given a specific DatoCMS record, returns an array of preview link(s).

The plugin performs a POST request to the Previews webhook URL, passing a payload that includes the current environment, record and model:

{
  "item": {…},
  "itemType": {…},
  "currentUser": {…},
  "siteId": "123",
  "environmentId": "main",
  "locale": "en",
}

• item: CMA entity of the current record
• itemType: CMA entity of the model of the current record
• currentUser: CMA entity of the collaborator, SSO user or account owner currently logged in
• siteId: the ID of the current DatoCMS project
• environmentId: the current environment ID
• locale: the locale currently active on the form

The endpoint is expected to return a 200 response, with the following JSON structure:

{
  "previewLinks": [
    {
      "label": "Published (en)",
      "url": "https://mysite.com/blog/my-article"
    },
    {
      "label": "Draft (en)",
      "url": "https://mysite.com/api/preview/start?slug=/blog/my-article"
    }
  ]
}

The plugin will show all the preview links that are returned. If you want to make sure that a preview's URL is reloaded after each save, you can include an extra option (please be aware that because of cross-origin iframe issues, maintaining the scroll position between reloads will not be possible):

{
  "label": "Draft (en)",
  "url": "https://mysite.com/api/preview/start?slug=/blog/my-article",
  "reloadPreviewOnRecordUpdate": { "delayInMs": 100 }
}

Implementation examples

If you have built alternative endpoint implementations for other frameworks/SSGs, please open up a PR to this plugin and share it with the community!

Next.js

We suggest you look at the code of our official Starter Kit:

• Route handler for the Previews webhook: app/api/preview-links/route.tsx
• Route handlers to toggle Next.js Draft Mode: app/api/draft-mode/enable/route.tsx and app/api/draft-mode/disable/route.tsx

The preview link URLs also include a token query parameter that the plugin would send to the webhook receiver, like https://www.mywebsite.com/api/preview-links?token=some-secret-ish-string. The token is a string of your choice that just has to match in both the plugin settings and in your frontend's environment variables. While not encryption, this token is an easy way to limit access to your preview content.

Nuxt

We suggest you look at the code of our official Starter Kit:

• Route handler called for the Previews webhook server/api/preview-links/index.ts
• Route handlers to toggle draft mode: server/api/draft-mode/enable.ts and server/api/draft-mode/disable.ts

The preview link URLs also include a token query parameter that the plugin would send to the webhook receiver, like https://www.mywebsite.com/api/preview-links?token=some-secret-ish-string. The token is a string of your choice that just has to match in both the plugin settings and in your frontend's environment variables. While not encryption, this token is an easy way to limit access to your preview content.

SvelteKit

We suggest you look at the code of our official Starter Kit:

• Route handler for the Previews webhook: src/routes/api/preview-links/+server.ts
• Route handlers to toggle draft mode: routes/api/draft-mode/enable/+server.ts and routes/api/draft-mode/disable/+server.ts

The preview link URLs also include a token query parameter that the plugin would send to the webhook receiver, like https://www.mywebsite.com/api/preview-links?token=some-secret-ish-string. The token is a string of your choice that just has to match in both the plugin settings and in your frontend's environment variables. While not encryption, this token is an easy way to limit access to your preview content.

Astro

We suggest you look at the code of our official Starter Kit:

• Route handler for the Previews webhook: src/pages/api/preview-links/index.ts
• Route handlers to toggle draft mode: src/pages/api/draft-mode/enable/index.ts and src/pages/api/draft-mode/disable/index.ts

The preview link URLs also include a token query parameter that the plugin would send to the webhook receiver, like https://www.mywebsite.com/api/preview-links?token=some-secret-ish-string. The token is a string of your choice that just has to match in both the plugin settings and in your frontend's environment variables. While not encryption, this token is an easy way to limit access to your preview content.