feat(static-renderer): add `@tiptap/static-renderer` to enable static rendering of content #5528

nperez0111 · 2024-08-20T20:13:17Z

@tiptap/static-renderer

The @tiptap/static-renderer package provides a way to render a Tiptap/ProseMirror document to any target format, like an HTML string, a React component, or even markdown.

Why Static Render?

The main use case for static rendering is to render a Tiptap/ProseMirror document on the server-side, for example in a Next.js or Nuxt.js application. This way, you can render the content of your editor to HTML before sending it to the client, which can improve the performance of your application.

Another use case is to render the content of your editor to another format like markdown, which can be useful if you want to send it to a markdown-based API.

But what makes it static? The static renderer doesn't require a browser or a DOM to render the content. It's a pure JavaScript function that takes a document (as JSON or Prosemirror Node instance) and returns the target format back.

Example

Render a Tiptap document to an HTML string:

import StarterKit from '@tiptap/starter-kit'
import { renderToHTMLString } from '@tiptap/static-renderer'

renderToHTMLString({
  extensions: [StarterKit], // using your extensions
  // we can map nodes and marks to HTML elements
  options: {
    nodeMapping: {
      // custom node mappings
    },
    markMapping: {
      // custom mark mappings
    },
    unhandledNode: ({ node }) => {
      // handle unhandled nodes
      return `[unknown node ${node.type.name}]`
    },
    unhandledMark: ({ mark }) => {
      // handle unhandled marks
      return `[unknown node ${mark.type.name}]`
    },
  },
  // the source content to render
  content: {
    type: 'doc',
    content: [
      {
        type: 'paragraph',
        content: [
          {
            type: 'text',
            text: 'Hello World!',
          },
        ],
      },
    ],
  },
})
// returns: '<p>Hello World!</p>'

Render to a React component:

import StarterKit from '@tiptap/starter-kit'
import { renderToReactElement } from '@tiptap/static-renderer'

renderToReactElement({
  extensions: [StarterKit], // using your extensions
  // we can map nodes and marks to HTML elements
  options: {
    nodeMapping: {
      // custom node mappings
    },
    markMapping: {
      // custom mark mappings
    },
    unhandledNode: ({ node }) => {
      // handle unhandled nodes
      return `[unknown node ${node.type.name}]`
    },
    unhandledMark: ({ mark }) => {
      // handle unhandled marks
      return `[unknown node ${mark.type.name}]`
    },
  },
  // the source content to render
  content: {
    type: 'doc',
    content: [
      {
        type: 'paragraph',
        content: [
          {
            type: 'text',
            text: 'Hello World!',
          },
        ],
      },
    ],
  },
})
// returns a react node that, when evaluated, would be equivalent to: '<p>Hello World!</p>'

There are a number of options available to customize the output, like custom node and mark mappings, or handling unhandled nodes and marks.

API

`renderToHTMLString`

function renderToHTMLString(options: {
  extensions: Extension[],
  content: ProsemirrorNode | JSONContent,
  options?: TiptapHTMLStaticRendererOptions,
}): string

`renderToHTMLString` Options

extensions: An array of Tiptap extensions that are used to render the content.
content: The content to render. Can be a Prosemirror Node instance or a JSON representation of a Prosemirror document.
options: An object with additional options.
options.nodeMapping: An object that maps Prosemirror nodes to HTML strings.
options.markMapping: An object that maps Prosemirror marks to HTML strings.
options.unhandledNode: A function that is called when an unhandled node is encountered.
options.unhandledMark: A function that is called when an unhandled mark is encountered.

`renderToReactElement`

function renderToReactElement(options: {
  extensions: Extension[],
  content: ProsemirrorNode | JSONContent,
  options?: TiptapReactStaticRendererOptions,
}): ReactElement

`renderToReactElement` Options

extensions: An array of Tiptap extensions that are used to render the content.
content: The content to render. Can be a Prosemirror Node instance or a JSON representation of a Prosemirror document.
options: An object with additional options.
options.nodeMapping: An object that maps Prosemirror nodes to React components.
options.markMapping: An object that maps Prosemirror marks to React components.
options.unhandledNode: A function that is called when an unhandled node is encountered.
options.unhandledMark: A function that is called when an unhandled mark is encountered.

How does it work?

Each Tiptap node/mark extension can define a renderHTML method which is used to generate default mappings of Prosemirror nodes/marks to the target format. These can be overridden by providing custom mappings in the options. One thing to note is that the static renderer doesn't support node views automatically, so you need to provide a mapping for each node type that you want rendered as a node view. Here is an example of how you can render a node view as a React component:

import { Node } from '@tiptap/core'
import { ReactNodeViewRenderer } from '@tiptap/react'
import StarterKit from '@tiptap/starter-kit'
import { renderToReactElement } from '@tiptap/static-renderer'

// This component does not have a NodeViewContent, so it does not render it's children's rich text content
function MyCustomComponentWithoutContent() {
  const [count, setCount] = React.useState(200)

  return (
    <div className='custom-component-without-content' onClick={() => setCount(a => a + 1)}>
      {count} This is a react component!
    </div>
  )
}

const CustomNodeExtensionWithoutContent = Node.create({
  name: 'customNodeExtensionWithoutContent',
  atom: true,
  renderHTML() {
    return ['div', { class: 'my-custom-component-without-content' }] as const
  },
  addNodeView() {
    return ReactNodeViewRenderer(MyCustomComponentWithoutContent)
  },
})

renderToReactElement({
  extensions: [StarterKit, CustomNodeExtensionWithoutContent],
  options: {
    nodeMapping: {
      // render the custom node with the intended node view React component
      customNodeExtensionWithoutContent: MyCustomComponentWithoutContent,
    },
  },
  content: {
    type: 'doc',
    content: [
      {
        type: 'customNodeExtensionWithoutContent',
      },
    ],
  },
})
// returns: <div class="my-custom-component-without-content">200 This is a react component!</div>

But what if you want to render the rich text content of the node view? You can do that by providing a NodeViewContent component as a child of the node view component:

import { Node } from '@tiptap/core'
import {
  NodeViewContent,
  ReactNodeViewContentProvider,
  ReactNodeViewRenderer
} from '@tiptap/react'
import StarterKit from '@tiptap/starter-kit'
import { renderToReactElement } from '@tiptap/static-renderer'


// This component does have a NodeViewContent, so it will render it's children's rich text content
function MyCustomComponentWithContent() {
  return (
    <div className="custom-component-with-content">
      Custom component with content in React!
      <NodeViewContent />
    </div>
  )
}


const CustomNodeExtensionWithContent = Node.create({
  name: 'customNodeExtensionWithContent',
  content: 'text*',
  group: 'block',
  renderHTML() {
    return ['div', { class: 'my-custom-component-with-content' }, 0] as const
  },
  addNodeView() {
    return ReactNodeViewRenderer(MyCustomComponentWithContent)
  },
})


renderToReactElement({
  extensions: [StarterKit, CustomNodeExtensionWithContent],
  options: {
    nodeMapping: {
      customNodeExtensionWithContent: ({ children }) => {
        // To pass the content down into the NodeViewContent component, we need to wrap the custom component with the ReactNodeViewContentProvider
        return (
          <ReactNodeViewContentProvider content={children}>
            <MyCustomComponentWithContent />
          </ReactNodeViewContentProvider>
        )
      },
    },
  },
  content: {
    type: 'doc',
    content: [
      {
        type: 'customNodeExtensionWithContent',
        // rich text content
        content: [
          {
            type: 'text',
            text: 'Hello, world!',
          },
        ],
      },
    ],
  },
})

// returns: <div class="custom-component-with-content">Custom component with content in React!<div data-node-view-content="" style="white-space:pre-wrap">Hello, world!</div></div>
// Note: The NodeViewContent component is rendered as a div with the attribute data-node-view-content, and the rich text content is rendered inside of it

changeset-bot · 2024-08-20T20:13:21Z

⚠️ No Changeset found

Latest commit: a9d1c6f

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

netlify · 2024-08-20T20:13:32Z

✅ Deploy Preview for tiptap-embed ready!

Name	Link
🔨 Latest commit	`a9d1c6f`
🔍 Latest deploy log	https://app.netlify.com/sites/tiptap-embed/deploys/67629085e3b7350008c9df44
😎 Deploy Preview	https://deploy-preview-5528--tiptap-embed.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

nperez0111 · 2024-08-23T17:30:09Z

packages/static-renderer/src/pm/react.tsx

+const schema = getSchema([StarterKit])
+
+console.log(
+  renderToStaticMarkup(


This is just a demo

bdbch

LGTM! Awesome idea @nperez0111

nperez0111 · 2024-08-28T21:29:39Z

Just as a note, if we render to something like jsx-dom then we can render directly to HTMLElements with pure JS & prosemirror

dcneiner · 2024-09-16T20:00:03Z

@nperez0111 I am super excited about this PR (finally took a look at it over the weekend). I tried building it locally today to test it out, and it failed because there was no src/index.ts file in the new static-renderer folder. Is there a pre-build step I was missing? I just added one locally to get past that.

Edit: Ah, its the same error currently failing the build CI step. You are probably already aware of this then!

nperez0111 · 2024-09-17T06:23:17Z

@nperez0111 I am super excited about this PR (finally took a look at it over the weekend). I tried building it locally today to test it out, and it failed because there was no src/index.ts file in the new static-renderer folder. Is there a pre-build step I was missing? I just added one locally to get past that.

Edit: Ah, its the same error currently failing the build CI step. You are probably already aware of this then!

Yep, this isn't completely prime-time yet. Needs a lot more tests to ensure things actually work

bdbch · 2024-11-30T07:47:20Z

@nperez0111 I'll remove my review - let me check if I should review in the future.

pkg-pr-new · 2024-12-04T16:53:13Z

Open in Stackblitz

@tiptap/core

npm i https://pkg.pr.new/@tiptap/core@5528

@tiptap/extension-blockquote

npm i https://pkg.pr.new/@tiptap/extension-blockquote@5528

@tiptap/extension-bubble-menu

npm i https://pkg.pr.new/@tiptap/extension-bubble-menu@5528

@tiptap/extension-bold

npm i https://pkg.pr.new/@tiptap/extension-bold@5528

@tiptap/extension-bullet-list

npm i https://pkg.pr.new/@tiptap/extension-bullet-list@5528

@tiptap/extension-character-count

npm i https://pkg.pr.new/@tiptap/extension-character-count@5528

@tiptap/extension-code

npm i https://pkg.pr.new/@tiptap/extension-code@5528

@tiptap/extension-code-block

npm i https://pkg.pr.new/@tiptap/extension-code-block@5528

@tiptap/extension-code-block-lowlight

npm i https://pkg.pr.new/@tiptap/extension-code-block-lowlight@5528

@tiptap/extension-collaboration

npm i https://pkg.pr.new/@tiptap/extension-collaboration@5528

@tiptap/extension-collaboration-cursor

npm i https://pkg.pr.new/@tiptap/extension-collaboration-cursor@5528

@tiptap/extension-color

npm i https://pkg.pr.new/@tiptap/extension-color@5528

@tiptap/extension-document

npm i https://pkg.pr.new/@tiptap/extension-document@5528

@tiptap/extension-dropcursor

npm i https://pkg.pr.new/@tiptap/extension-dropcursor@5528

@tiptap/extension-floating-menu

npm i https://pkg.pr.new/@tiptap/extension-floating-menu@5528

@tiptap/extension-focus

npm i https://pkg.pr.new/@tiptap/extension-focus@5528

@tiptap/extension-font-family

npm i https://pkg.pr.new/@tiptap/extension-font-family@5528

@tiptap/extension-gapcursor

npm i https://pkg.pr.new/@tiptap/extension-gapcursor@5528

@tiptap/extension-hard-break

npm i https://pkg.pr.new/@tiptap/extension-hard-break@5528

@tiptap/extension-heading

npm i https://pkg.pr.new/@tiptap/extension-heading@5528

@tiptap/extension-highlight

npm i https://pkg.pr.new/@tiptap/extension-highlight@5528

@tiptap/extension-history

npm i https://pkg.pr.new/@tiptap/extension-history@5528

@tiptap/extension-horizontal-rule

npm i https://pkg.pr.new/@tiptap/extension-horizontal-rule@5528

@tiptap/extension-image

npm i https://pkg.pr.new/@tiptap/extension-image@5528

@tiptap/extension-italic

npm i https://pkg.pr.new/@tiptap/extension-italic@5528

@tiptap/extension-link

npm i https://pkg.pr.new/@tiptap/extension-link@5528

@tiptap/extension-list-item

npm i https://pkg.pr.new/@tiptap/extension-list-item@5528

@tiptap/extension-list-keymap

npm i https://pkg.pr.new/@tiptap/extension-list-keymap@5528

@tiptap/extension-mention

npm i https://pkg.pr.new/@tiptap/extension-mention@5528

@tiptap/extension-ordered-list

npm i https://pkg.pr.new/@tiptap/extension-ordered-list@5528

@tiptap/extension-paragraph

npm i https://pkg.pr.new/@tiptap/extension-paragraph@5528

@tiptap/extension-placeholder

npm i https://pkg.pr.new/@tiptap/extension-placeholder@5528

@tiptap/extension-strike

npm i https://pkg.pr.new/@tiptap/extension-strike@5528

@tiptap/extension-subscript

npm i https://pkg.pr.new/@tiptap/extension-subscript@5528

@tiptap/extension-superscript

npm i https://pkg.pr.new/@tiptap/extension-superscript@5528

@tiptap/extension-table-cell

npm i https://pkg.pr.new/@tiptap/extension-table-cell@5528

@tiptap/extension-table

npm i https://pkg.pr.new/@tiptap/extension-table@5528

@tiptap/extension-table-header

npm i https://pkg.pr.new/@tiptap/extension-table-header@5528

@tiptap/extension-table-row

npm i https://pkg.pr.new/@tiptap/extension-table-row@5528

@tiptap/extension-task-item

npm i https://pkg.pr.new/@tiptap/extension-task-item@5528

@tiptap/extension-task-list

npm i https://pkg.pr.new/@tiptap/extension-task-list@5528

@tiptap/extension-text

npm i https://pkg.pr.new/@tiptap/extension-text@5528

@tiptap/extension-text-align

npm i https://pkg.pr.new/@tiptap/extension-text-align@5528

@tiptap/extension-text-style

npm i https://pkg.pr.new/@tiptap/extension-text-style@5528

@tiptap/extension-underline

npm i https://pkg.pr.new/@tiptap/extension-underline@5528

@tiptap/extension-typography

npm i https://pkg.pr.new/@tiptap/extension-typography@5528

@tiptap/extension-youtube

npm i https://pkg.pr.new/@tiptap/extension-youtube@5528

@tiptap/html

npm i https://pkg.pr.new/@tiptap/html@5528

@tiptap/pm

npm i https://pkg.pr.new/@tiptap/pm@5528

@tiptap/react

npm i https://pkg.pr.new/@tiptap/react@5528

@tiptap/starter-kit

npm i https://pkg.pr.new/@tiptap/starter-kit@5528

@tiptap/static-renderer

npm i https://pkg.pr.new/@tiptap/static-renderer@5528

@tiptap/suggestion

npm i https://pkg.pr.new/@tiptap/suggestion@5528

@tiptap/vue-2

npm i https://pkg.pr.new/@tiptap/vue-2@5528

@tiptap/vue-3

npm i https://pkg.pr.new/@tiptap/vue-3@5528

commit: a9d1c6f

…act Context

…ing & React Elements

…arks

packages/static-renderer/src/helpers.ts

masylum · 2024-12-19T16:45:01Z

I think there is a bug when using namespaces:

https://github.com/ProseMirror/prosemirror-model/blob/3c0b054fbdeabbf45836b3441ec8ce5da8da2e5d/src/to_dom.js#L126C1-L131C106

this should work:

renderHTML({ HTMLAttributes, node }) {
	const { iconValue, title } = node.attrs

	return [
		[
			"div",
			{
				"data-type": ALERT_ICON_NODE,
			},
			[
				"http://www.w3.org/2000/svg svg",
				{
					width: 24,
					height: 24,
					"stroke-width": 2,
					stroke: "currentColor",
					"stroke-linecap": "round",
					fill: "none",
				},
				["title", {}, iconValue],
				[
					"use",
					{ "http://www.w3.org/1999/xlink xlink:href": `#${iconValue}` },
				],
			],
		],
	] as any
}

Specifically, the "http://www.w3.org/2000/svg svg"

nperez0111 · 2024-12-20T21:05:09Z

Welp, didn't know about that feature, I'll have to get back to you on this

nperez0111 requested review from bdbch and svenadlung as code owners August 20, 2024 20:13

nperez0111 force-pushed the node-view-content branch from 2162826 to 64dae06 Compare August 23, 2024 16:02

nperez0111 commented Aug 23, 2024

View reviewed changes

bdbch approved these changes Aug 27, 2024

View reviewed changes

nperez0111 changed the title ~~feat: allowing specifying the content of ReacNodeViewContent via a React Context~~ feat(static-renderer): add @tiptap/static-renderer to enable static rendering of content Aug 27, 2024

nperez0111 mentioned this pull request Aug 29, 2024

[Bug]: @tiptap/html no longer handles style attributes correctly #5352

Open

1 task

nperez0111 force-pushed the node-view-content branch from 474ff43 to 21fa3aa Compare November 20, 2024 15:39

bdbch self-requested a review November 30, 2024 07:47

nperez0111 changed the base branch from develop to next December 4, 2024 15:34

nperez0111 force-pushed the node-view-content branch 3 times, most recently from 5645687 to bc7ad50 Compare December 4, 2024 16:05

nperez0111 mentioned this pull request Dec 9, 2024

How do you render html without the Editor ? #657

Closed

nperez0111 added 9 commits December 16, 2024 16:45

feat: allowing specifying the content of ReacNodeViewContent via a Re…

1a5bf6e

…act Context

refactor: export resolveExtensions function

e5a5680

feat: first version of a static renderer

5f8512d

feat(static-renderer): firm up the API and have it render to HTML Str…

579d18d

…ing & React Elements

chore: minor change

303de65

docs: more examples

0f47e0e

fix: better handling of unhandledNode & unhandledMark

6964c50

chore: add export

d82f1cb

feat: add support for providing the current node and parent node to m…

83eddd8

…arks

nperez0111 added 4 commits December 16, 2024 16:45

build: setup package to be built by tsup instead

a61e1c9

build: fix build

8bd5241

chore: make package public

7601c36

feat(static-renderer): add markdown output support

d42fb8e

nperez0111 force-pushed the node-view-content branch from 479d895 to d42fb8e Compare December 16, 2024 15:46

masylum reviewed Dec 17, 2024

View reviewed changes

packages/static-renderer/src/helpers.ts Outdated Show resolved Hide resolved

nperez0111 added 2 commits December 18, 2024 09:25

fix: access nodeOrMark's type safely across JSON & Prosemirror objects

a5c3094

chore: widen the type to represent the actual representation

a9d1c6f

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(static-renderer): add `@tiptap/static-renderer` to enable static rendering of content #5528

feat(static-renderer): add `@tiptap/static-renderer` to enable static rendering of content #5528

nperez0111 commented Aug 20, 2024 •

edited

Loading

changeset-bot bot commented Aug 20, 2024 •

edited

Loading

netlify bot commented Aug 20, 2024 •

edited

Loading

nperez0111 Aug 23, 2024

bdbch left a comment

nperez0111 commented Aug 28, 2024

dcneiner commented Sep 16, 2024 •

edited

Loading

nperez0111 commented Sep 17, 2024

bdbch commented Nov 30, 2024

pkg-pr-new bot commented Dec 4, 2024 •

edited

Loading

masylum commented Dec 19, 2024 •

edited

Loading

nperez0111 commented Dec 20, 2024

feat(static-renderer): add @tiptap/static-renderer to enable static rendering of content #5528

Are you sure you want to change the base?

feat(static-renderer): add @tiptap/static-renderer to enable static rendering of content #5528

Conversation

nperez0111 commented Aug 20, 2024 • edited Loading

@tiptap/static-renderer

Why Static Render?

Example

API

renderToHTMLString

renderToHTMLString Options

renderToReactElement

renderToReactElement Options

How does it work?

changeset-bot bot commented Aug 20, 2024 • edited Loading

⚠️ No Changeset found

netlify bot commented Aug 20, 2024 • edited Loading

✅ Deploy Preview for tiptap-embed ready!

nperez0111 Aug 23, 2024

Choose a reason for hiding this comment

bdbch left a comment

Choose a reason for hiding this comment

nperez0111 commented Aug 28, 2024

dcneiner commented Sep 16, 2024 • edited Loading

nperez0111 commented Sep 17, 2024

bdbch commented Nov 30, 2024

pkg-pr-new bot commented Dec 4, 2024 • edited Loading

masylum commented Dec 19, 2024 • edited Loading

nperez0111 commented Dec 20, 2024

feat(static-renderer): add `@tiptap/static-renderer` to enable static rendering of content #5528

feat(static-renderer): add `@tiptap/static-renderer` to enable static rendering of content #5528

nperez0111 commented Aug 20, 2024 •

edited

Loading

`renderToHTMLString`

`renderToHTMLString` Options

`renderToReactElement`

`renderToReactElement` Options

changeset-bot bot commented Aug 20, 2024 •

edited

Loading

netlify bot commented Aug 20, 2024 •

edited

Loading

dcneiner commented Sep 16, 2024 •

edited

Loading

pkg-pr-new bot commented Dec 4, 2024 •

edited

Loading

masylum commented Dec 19, 2024 •

edited

Loading