Tiptap YouTube extension: preserve a video node through save and reopen

An original equipment-training note places a short setup video between “Check the power supply” and “Run the calibration.” If the player appears while editing but vanishes after reopening, inspect the saved document and the receiving editor's extensions before adjusting the player's CSS.

Register the node in the configured editor

In an existing Tiptap application, import the extension and add the configured result to the editor's current extension array:

import Youtube from '@tiptap/extension-youtube';

const trainingVideoExtension = Youtube.configure({
  inline: false,
  width: 640,
  height: 360,
  controls: true,
  autoplay: false,
  nocookie: true
});

Keep the application's document, paragraph, history, and other extensions. This fragment defines one extension; it does not create an editor, install dependencies, or save the document.

The block setting lets the video sit between the training note's paragraphs. Width and height supply insertion defaults, not a complete responsive layout. The nocookie setting selects the extension's documented no-cookie embed mode. It does not establish that the entire page is anonymous, remove every external request, or replace your application's consent requirements.

Insert the approved video through the command

After the author places the selection between the two instructions, the application's insert control can run:

// approvedVideoUrl is the real YouTube URL selected by the author.
const inserted = editor.commands.setYoutubeVideo({
  src: approvedVideoUrl,
  width: 640,
  height: 360
});

if (!inserted) {
  showInsertError('The video could not be inserted here.');
}

editor, approvedVideoUrl, and showInsertError belong to the existing application. Supply those values and its normal URL checks. Do not use a training-video address invented for a sample.

The extension documents YouTube and YouTube Music URLs for src. Its command inserts at the current document position. An external dialog must keep or restore the intended selection, otherwise a valid video may land elsewhere in the note. Read the surrounding instruction again after insertion.

Follow the document through its actual storage format

At Save, capture the current document through the application's established representation:

const trainingJson = editor.getJSON();
const trainingHtml = editor.getHTML();

These are two representations to inspect, not a requirement to store both. Keep whichever is the application's source of truth. Saving an older initialization variable can omit the new video even when the editor currently displays it.

For JSON storage, inspect the video node and its attributes, then load the record into an editor that includes compatible YouTube support. For HTML storage, inspect the serialized embed and the server's permitted markup before reopening. A sanitizer that removes iframes needs a deliberate integration policy; allowing arbitrary iframe HTML is broader than supporting approved YouTube video nodes.

Compare the document immediately before saving, the stored record, and the reopened document. That identifies whether the loss happens during extraction, storage transformation, or parsing into the receiving editor. The Tiptap image workflow covers another media path; its file-upload callbacks do not insert YouTube nodes.

Test the reader's player separately

Inspect the actual serialized player wrapper and apply responsive content styles in both authoring and reader contexts. A 640-pixel insertion width must not force the surrounding note wider than a phone screen. Avoid styling every iframe on the site when only training-video embeds need that rule.

Keep a written description and an ordinary link to the approved video beside it. If the owner disallows embedding or the reader's network blocks YouTube, preserving a node cannot make playback succeed. The HTML YouTube embed guide explains those player-level failures.

For the equipment note, save and reopen the document, confirm that the player still sits between the correct two instructions, and test playback under the intended reader's access conditions. A surviving embed and a playable video are separate acceptance checks.