Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
wants to merge 9 commits into
base: develop
Choose a base branch
from

Conversation

nperez0111
Copy link
Contributor

@nperez0111 nperez0111 commented Aug 20, 2024

@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

Copy link

changeset-bot bot commented Aug 20, 2024

⚠️ No Changeset found

Latest commit: 474ff43

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

Copy link

netlify bot commented Aug 20, 2024

Deploy Preview for tiptap-embed ready!

Name Link
🔨 Latest commit 474ff43
🔍 Latest deploy log https://app.netlify.com/sites/tiptap-embed/deploys/66f5596d422acc000855ea2b
😎 Deploy Preview https://deploy-preview-5528--tiptap-embed.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

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

const schema = getSchema([StarterKit])

console.log(
renderToStaticMarkup(
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is just a demo

Copy link
Contributor

@bdbch bdbch left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! Awesome idea @nperez0111

@nperez0111 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
Copy link
Contributor Author

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

@dcneiner
Copy link

dcneiner commented Sep 16, 2024

@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
Copy link
Contributor Author

@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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Status: Ready to Merge
Development

Successfully merging this pull request may close these issues.

3 participants