Transitioning from customRules to customNodeRules in react-datocms – Compatibility Inquiry

🆘 Support
1

Hi DatoCMS Support,

We’ve been using customRules in combination with renderRule within the component of the react-datocms library to handle custom rendering logic. We’ve noticed that customRules is now marked as deprecated and understand that we should migrate to customNodeRules.

Before proceeding with the migration, we’d like to ensure that this change won’t affect any existing logic tied to our custom renderers. Specifically, we make extensive use of the following type guard functions to determine the node types during rendering:

function isHeading(node: Node): node is Heading {}
function isParagraph(node: Node): node is Paragraph {}
function isListItem(node: Node): node is ListItem {}
function isBlockquote(node: Node): node is Blockquote {}
function isLink(node: Node): node is Link {}

Could you please confirm:

  1. Whether these type guard functions remain fully compatible and behave identically when used with customNodeRules instead of customRules?
  2. Whether we should consider using renderNodeRule in place of renderRule going forward?
2

Hey there,

You can go ahead with the switch without worrying about your existing type guards. The helpers exported by datocms‑structured‑text‑utils such as isHeading, isParagraph, isListItem, isBlockquote, and isLink have not changed and still accept the very same Node objects that reach your rules. Their TypeScript signatures and narrowing behaviour are identical, so any logic that depends on them will keep working as‑is .

customNodeRules is simply the new, clearer name for the old customRules prop… No other code changes are required . The official docs already use customNodeRules, so you can look at those examples as a drop‑in guide .

The same applies to the helper used to create the rule itself: renderNodeRule replaces the older renderRule. Today renderRule is just an alias that re‑exports renderNodeRule, but it carries a deprecation notice in the source. Importing renderNodeRule is therefore the forward‑compatible choice .

Putting it all together, your migration can be as small as:

import { StructuredText, renderNodeRule } from 'react-datocms';
import {
  isHeading,
  isParagraph,
  isListItem,
  isBlockquote,
  isLink,
} from 'datocms-structured-text-utils';

<StructuredText
  data={data}
  customNodeRules={[
    renderNodeRule(isHeading, ({ node, children, key }) => {
      const Tag = `h${node.level}` as const;
      return <Tag key={key}>{children}</Tag>;
    }),
    // …your other rules stay exactly the same
  ]}
  /* any other props unchanged */
 />;

That is all that is needed.

3

Thanks much for the guidance!