Migrating from ReactMarkdown to Tiptap for Enhanced Markdown Rendering in Next.js

The evolution of web applications often necessitates upgrading or replacing existing components to leverage new features, improve performance, or gain greater control over functionality. In the context of rendering Markdown content within a Next.js project, a transition from a dedicated rendering component like react-markdown to a more comprehensive rich text editor framework such as Tiptap, utilizing the tiptap-markdown extension, presents both opportunities and challenges. While react-markdown efficiently handles the basic task of displaying Markdown, Tiptap's underlying architecture as a full-fledged editor provides a foundation for future enhancements, including the potential to introduce in-place editing capabilities directly within the conversation interface ¹. This move towards a more robust framework allows for greater flexibility and customization, addressing requirements such as precise styling, nuanced handling of different message roles in a conversation, and the accurate rendering of interactive elements like task lists. The process of migrating to Tiptap involves careful consideration of installation, initial content rendering, managing different content types, styling to maintain visual consistency, and handling dynamic data streams.

Setting Up Tiptap with Markdown in a Next.js Environment

The initial step in integrating Tiptap with Markdown rendering capabilities into a Next.js project involves installing the necessary packages. This is achieved using either npm or yarn, the package managers commonly employed in JavaScript-based projects. The core Tiptap libraries, including @tiptap/core and @tiptap/react, are fundamental as they provide the base editor functionality and the React‑specific bindings required to use Tiptap components within a Next.js application ². Additionally, the @tiptap/starter‑kit offers a collection of essential extensions that add basic but crucial functionalities to the editor, such as support for paragraphs, headings, and fundamental text formatting options like bold and italic ². Finally, the tiptap‑markdown package is the key to enabling Markdown parsing and rendering within the Tiptap editor. These packages can be installed by running the following commands in the root directory of the Next.js project:

Bash

npm install @tiptap/core @tiptap/react @tiptap/starter-kit tiptap-markdown

or

Bash

yarn add @tiptap/core @tiptap/react @tiptap/starter-kit tiptap-markdown

It is important to ensure that the core Tiptap packages are installed alongside tiptap‑markdown as the latter depends on the former to function correctly. Specifically, tiptap‑markdown leverages @tiptap/core for its integration with the Tiptap editor and relies on the prosemirror‑markdown library, which is part of the ProseMirror ecosystem, for the actual parsing and serialization of Markdown syntax.

Rendering Initial Markdown Content in Tiptap

Once the necessary packages are installed, the next step involves configuring a Tiptap editor instance to display existing Markdown content. The tiptap‑markdown extension allows for the direct use of Markdown strings as initial content through the content option provided in the useEditor hook ³. This hook is the primary way to create and manage a Tiptap editor instance within a React component. By including the Markdown extension in the extensions array passed to useEditor, the editor becomes capable of interpreting Markdown content. The following code snippet illustrates how this can be implemented:

JavaScript

import React from "react";
import { useEditor, EditorContent } from "@tiptap/react";
import StarterKit from "@tiptap/starter-kit";
import Markdown from "tiptap-markdown";
 
const MyTiptapEditor = ({ initialMarkdownContent }) => {
  const editor = useEditor({
    extensions: [StarterKit, Markdown],
    content: initialMarkdownContent, // Pass your Markdown string here
  });
 
  if (!editor) {
    return null;
  }
 
  return <EditorContent editor={editor} />;
};
 
export default MyTiptapEditor;

In this example, the initialMarkdownContent prop, which will receive the Markdown string from the message.content of the ConversationItem, is directly assigned to the content option of the editor. Tiptap employs a schema to define the structure and rules for the content it manages, ⁴, ⁴, ⁴. When tiptap‑markdown encounters a Markdown string provided as initial content, it parses this string and transforms it into a structured document representation that adheres to the enabled extensions and the underlying ProseMirror schema ⁵. This structured format ensures consistency in rendering and enables further manipulation of the content within the Tiptap editor.

Managing Conversation Flow: Handling User and Assistant Roles

To effectively display a conversation within a single Tiptap editor instance, it is crucial to visually differentiate between messages from the user and the assistant. One approach to achieve this involves defining custom node types within Tiptap: UserMessage and AssistantMessage ². These custom nodes extend Tiptap's functionality to represent distinct types of content within the editor. Defining a custom node extension typically involves specifying properties such as name (a unique identifier), group (which helps categorize the node within the schema, likely block for messages), and content (defining what kind of content the node can contain, such as paragraph* to allow one or more paragraphs within a message) ⁴.

To utilize these custom nodes, the incoming message data might need to be adapted. For instance, a simple role identifier (e.g., [user] or [assistant]) could be prepended to the Markdown content of each message. Subsequently, it becomes necessary to customize how tiptap‑markdown parses this content ⁶. The default Markdown parser will not inherently recognize these custom role identifiers. Customizing the parsing logic might involve extending the Markdown extension provided by tiptap‑markdown or implementing custom input rules within Tiptap that detect the role‑specific syntax and trigger the creation of the corresponding UserMessage or AssistantMessage nodes.

For scenarios requiring more complex rendering or interactive elements within user and assistant messages, Tiptap's Node Views offer a powerful mechanism ⁷. Node Views allow developers to render React components directly within the Tiptap editor, enabling highly customized and interactive content that goes beyond basic text and formatting. As an alternative, for simpler visual distinctions, applying attributes (e.g., role: 'user') to a base paragraph node and then using CSS to style the content based on these attributes can also be a viable approach. The group property defined for the custom message nodes plays a crucial role in determining where these nodes can be placed within the Tiptap document structure ⁴. By setting the group to block, for example, user and assistant messages will be treated as distinct block‑level elements in the conversation flow.

Styling Tiptap Content for Visual Consistency

A key requirement for migrating to Tiptap is to ensure that the rendered Markdown content visually matches the existing styling applied to the react‑markdown component within the user's ConversationItem. Tiptap is a "headless" editor framework, meaning it does not provide any default styling for the content it manages ⁵. Therefore, all styling must be implemented by targeting the HTML elements that Tiptap generates.

One effective way to apply custom styles is by utilizing the HTMLAttributes option within the definitions of the custom message nodes (UserMessage and AssistantMessage) ⁸. This option allows for the addition of custom CSS classes directly to the HTML elements rendered for these nodes. By assigning class names that mirror those used in the original ConversationItem component (e.g., bg-neutral-100, text-right, gap-2, p-4), the existing CSS rules can be leveraged. Additionally, the .tiptap class, which Tiptap adds to its main container element, can be used to scope styles specifically to the editor content if needed ⁹.

For example, to replicate the styling for user messages, the UserMessage node definition might include HTMLAttributes: { class: 'user-message-container' }, and the paragraph within it might have HTMLAttributes: { class: 'user-message-text' }. Corresponding CSS rules can then be defined:

CSS

.tiptap .user-message-container {
  display: flex;
  flex-direction: row;
  align-items: center;
  gap: 0.5rem; /* Equivalent to gap-2 */
  align-self: flex-end;
  border-radius: 1.5rem 1.5rem 0 1.5rem; /* Approximating rounded-full rounded-tr-none */
  background-color: #f3f4f6; /* Equivalent to bg-neutral-100 */
  padding: 1rem; /* Approximating px-4 */
  text-align: right;
}
 
.tiptap .user-message-text {
  width: 100%;
  border-radius: 1.5rem;
  padding: 0.5rem 1.5rem; /* Equivalent to p-2 px-6 */
  text-align: right;
  /* Add dark mode styles as well */
}
 
.tiptap .assistant-message {
  gap: 0.5rem; /* Equivalent to gap-2 */
  padding: 1rem; /* Equivalent to p-4 */
}

Rendering Task Lists with Tiptap Extensions

To ensure that todo items from the Markdown content are rendered correctly, similar to the CheckboxRenderer used with react‑markdown, Tiptap provides dedicated extensions: @tiptap/extension-task-list and @tiptap/extension-task-item, ¹⁰, ¹⁰, ¹⁰, ¹¹. These extensions can be installed using the following commands:

Bash

npm install @tiptap/extension-task-list @tiptap/extension-task-item

or

Bash

yarn add @tiptap/extension-task-list @tiptap/extension-task-item

Once installed, these extensions need to be included in the extensions array when initializing the Tiptap editor:

JavaScript

import React from "react";
import { useEditor, EditorContent } from "@tiptap/react";
import StarterKit from "@tiptap/starter-kit";
import Markdown from "tiptap-markdown";
import TaskList from "@tiptap/extension-task-list";
import TaskItem from "@tiptap/extension-task-item";
 
const MyTiptapEditor = ({ initialMarkdownContent }) => {
  const editor = useEditor({
    extensions: [StarterKit, Markdown, TaskList, TaskItem],
    content: initialMarkdownContent,
  });
 
  if (!editor) {
    return null;
  }
 
  return <EditorContent editor={editor} />;
};
 
export default MyTiptapEditor;

With these extensions registered, Tiptap should automatically recognize and render Markdown task list syntax (- [ ] for unchecked and - [x] for checked items) as interactive checkboxes within the editor. The @tiptap/extension-task-list provides the overall structure for the task list (<ul data-type="taskList">), while @tiptap/extension-task-item renders each individual task item (<li data-type="taskItem" data-checked="...">). These extensions offer configuration options such as nested to allow task items to be nested within each other and itemTypeName to customize the class name applied to task list items ¹¹. It is highly probable that the tiptap‑markdown extension relies on these dedicated task list extensions to correctly interpret and render task list items from the Markdown input. Therefore, ensuring that tiptap‑markdown is included alongside the task list extensions in the editor's configuration is essential. Snippets ¹² and ¹² indicate Tiptap's inherent support for Markdown shortcuts, which encompasses the standard syntax for creating task lists.

Considerations and Best Practices for Streaming Markdown Content

When replacing react‑markdown with Tiptap for rendering dynamic Markdown content from a streaming source, several factors need to be considered. While Tiptap is a performant editor, continuously appending large amounts of content, especially during a streaming process, can potentially lead to performance degradation ¹³.

Tiptap's Content AI module (which may require a subscription) provides the streamContent command, which is specifically designed for efficiently handling streaming content into the editor ¹⁴. This command allows for appending content at the end of the editor or replacing content within a specified range, offering more granular control over how streamed data is inserted. To use streamContent for appending new Markdown chunks from a streaming source like Vercel AI SDK, the end position of the editor's content needs to be determined using editor.state.doc.content.size. The streamContent command can then be called with this end position and a callback function that handles fetching and writing the streamed data using the provided write function.

For optimal performance and control, consider transforming the streamed Markdown content into Tiptap‑compatible HTML or JSON format on the backend or frontend before inserting it into the editor using streamContent ¹⁵, ¹⁶, ¹⁷, ¹⁸, ¹⁰. This pre‑processing step can reduce the load on the editor by providing data in a format it handles more efficiently. When integrating with Vercel AI SDK or similar streaming services, an API route in Next.js can be set up to handle the AI response as a stream, and Tiptap's streaming API can then be connected to this route2, S_R151, S_R154].

Finally, it is important to be aware of potential subtle differences in how Markdown syntax is interpreted and rendered between react‑markdown and tiptap‑markdown ¹⁹, ²⁰, ¹⁷, ¹⁸. Thoroughly testing the rendering of various Markdown elements, including any custom syntax or edge cases present in the message.content, is crucial to ensure visual consistency after the migration. Custom parsing rules within tiptap‑markdown might be necessary to address any discrepancies.

Conclusion and Next Steps

Migrating from react‑markdown to Tiptap with the tiptap‑markdown extension offers a pathway to a more extensible and feature‑rich solution for rendering Markdown content in a Next.js application. The process involves several key steps: installing the necessary Tiptap and Markdown‑related packages, setting up the editor to render initial Markdown content, defining custom node types (or using attributes) to manage and style user and assistant messages distinctly, applying CSS styles to ensure visual consistency with the existing implementation, integrating Tiptap's task list extensions to handle todo items, and carefully considering the implications and best practices for efficiently rendering content from a streaming source.

It is recommended to approach this migration iteratively. Starting with a basic implementation that focuses on rendering static Markdown content will provide a solid foundation. Subsequent steps can then address the more complex requirements, such as role‑based styling and the integration of task list functionality. For handling dynamic content from a streaming source, exploring Tiptap's streamContent command is advisable for optimized performance. Throughout the implementation process, thorough testing is essential to ensure that all Markdown elements are rendered correctly and that the visual appearance aligns with the original react‑markdown component. The official Tiptap documentation and the tiptap‑markdown repository serve as valuable resources for more advanced customization options and API details.

Works cited