Vercel Visual Editing is an exciting feature offered by Vercel's site preview. It enhances your website by adding clickable links to any content present in the page that's coming from your DatoCMS project. By simply clicking on these links, you'll be seamlessly directed to the corresponding record in DatoCMS.
Once configured for your project, the implementation will resemble the following example:
Right now, Vercel Visual editing is an opt-in Enterprise feature on Vercel side, while it's currently in beta testing for Enterprise DatoCMS customers. If you want to have the feature enabled in your DatoCMS projects, contact us at support@datocms.com.
When Vercel Visual Editing is enabled, DatoCMS's Content Delivery API incorporates hidden metadata into the response of the GraphQL queries you make.
This is achieved through a smart technique known as steganography. Steganography is the practice of concealing information within other data, and in this case, it involves encoding the metadata into invisible Unicode characters that are added to the existing strings — you can examine the complete encoding/decoding algorithm in the @vercel/stega NPM pagkage.
Once the "augmented strings" coming from DatoCMS are used in your pages, Vercel can locate and identify the hidden metadata in the final HTML, and display clickable links that direct you to the corresponding record in DatoCMS.
Currently, the metadata required to show a clickable link on Vercel is added in the following parts of the GraphQL response:
Text fields (both Single-line Strings and Multi-paragraph Text) that are not empty and with no format validation: the metadata will be appended at the end of the original string;
Structured Text fields: the metadata will be appended at the end of the last span node contained in the first paragraph, heading, list, code or blockquote node found in the document;
The alt field of any Upload referenced in the response: the metadata will be appended at the end of the original string;
We've been conservative in deciding in which cases to embed hidden metadata, so your website should not break when enabling Visual Editing, but still, it's crucial that you test it thoroughly. If you encounter any problem, please refer to the Troubleshooting section of this guide.
To leverage the powerful capabilities of Visual Editing, you can follow these straightforward steps to ensure its seamless integration into your workflow:
If you're an Enterprise customer of both DatoCMS and Vercel, please contact us at support@datocms.com: by providing the ID of the project where you want to enable visual editing, we'll be able to switch on the feature rapidly.
To communicate to DatoCMS's Content Delivery API that you want visual editing metadata included in your responses, you must add two headers to your API requests:
X-Visual-Editing is the header that enables the feature, and it must be set to vercel-v1;
X-Base-Editing-Url is required to generate the right link to your DatoCMS project: it's the base URL of the project on the CMS, and unless you're using a custom domain, it looks like https://example-project.admin.datocms.com
Here is an example of how to add the headers when using the standard fetch API. In this case, we're going to enable visual editing on every preview deployment of the website:
const visualEditingHeaders = process.env.VERCEL_ENV === "preview" ? {"X-Visual-Editing": "vercel-v1","X-Base-Editing-Url": "https://<YOUR-PROJECT-NAME>.admin.datocms.com"} : {}const response = await fetch("https://graphql-staging.datocms.com/",{method: "POST",headers: {"Authorization": "Bearer <API-KEY>",...visualEditingHeaders,},body: JSON.stringify({query, variables}),});
How you declare the headers depends on the client you're using: please refer to your GraphQL/HTTP client documentation for more info.
Although, in general, your website should not break when you enable Visual Editing, there may be special situations that can cause problems.
In some cases (e.g. when using letter-spacing in CSS), the editable elements could have unexpected style. In those cases, you can use the functions available in the @vercel/stega library to extract the content and remove steganography data.
Install the library
npm i @vercel/stega
Then you can use a library helper like this:
import { vercelStegaSplit } from '@vercel/stega';const { cleaned, encoded } = vercelStegaSplit(text);
If the wrong element is highlighted when you enable visual editing, you can add the data-vercel-edit-target attribute to one of the parent elements:
<div class="card" data-vercel-edit-target><h1>{editableTitle}</h1><div>Some more text</div></div>
That way, even if the editable element is the <h1>, you will have the full card highlighted.
Since the metadata added in the GraphQL response is encoded into invisible Unicode characters, it can be quite tricky to examine it.
Fortunately, when you enable the visual editing via the Vercel toolbar, a data-vercel-edit-info attribute is added to every element that contains steganography data: