Node.js - Plate — ContextQMD

This guide demonstrates how to use Plate in a Node.js environment. This is useful for backend tasks such as data processing, content migration, validation, or any scenario where you need to interact with Plate editor content without a browser or a full React frontend.

<Callout type="warning" title="Key Node.js Constraint"> When using Plate in a Node.js environment, you **must not** import from `/react` subpaths of any `platejs*` package. Always use the base imports (e.g., `@platejs/basic-nodes` instead of `@platejs/basic-nodes/react`).

This means you cannot use createPlateEditor from platejs/react. Instead, use createSlateEditor from platejs. </Callout>

<Steps>

Install Plate

Install the core Plate package and any specific plugin packages required for your data processing needs.

bash

npm install platejs @platejs/basic-nodes

platejs: The core Plate editor functionality.
@platejs/basic-nodes: Plugin for basic nodes like headings, bold, italic, underline, etc.

Create an Editor Instance

In your Node.js script, use createSlateEditor from platejs to initialize an editor instance. This function is framework-agnostic and doesn't depend on React or browser APIs.

typescript

import { createSlateEditor } from 'platejs';
import {
  BaseBoldPlugin,
  BaseItalicPlugin,
  BaseUnderlinePlugin,
  BaseH1Plugin,
  BaseH2Plugin,
  BaseH3Plugin,
  BaseBlockquotePlugin,
} from '@platejs/basic-nodes';

const initialValue = [
  {
    type: 'h3',
    children: [{ text: 'Document Title' }],
  },
  {
    type: 'blockquote',
    children: [{ text: 'This is a quote.' }],
  },
  {
    type: 'p',
    children: [
      { text: 'With some ' },
      { text: 'bold', bold: true },
      { text: ' text for emphasis!' },
    ],
  },
];

const editor = createSlateEditor({
  plugins: [
    BaseBoldPlugin,
    BaseItalicPlugin,
    BaseUnderlinePlugin,
    BaseH1Plugin,
    BaseH2Plugin,
    BaseH3Plugin,
    BaseBlockquotePlugin,
  ],
  value: initialValue,
});

// You can now use editor.children, editor.api, editor.tf, etc.
console.debug('Editor content:', editor.children);

<Callout type="info"> `createSlateEditor` creates a raw Plate editor instance suitable for server-side logic, data transformation, or preparing content for static rendering. It provides the same API as the React version but without browser dependencies. </Callout>

Content Manipulation

The primary use case for Plate in Node.js is programmatic content manipulation:

typescript

import { createSlateEditor } from 'platejs';
import {
  BaseBoldPlugin,
  BaseItalicPlugin,
  BaseH1Plugin,
  BaseH2Plugin,
  BaseH3Plugin,
  BaseBlockquotePlugin,
} from '@platejs/basic-nodes';

async function processDocument(value: any[]) {
  const editor = createSlateEditor({
    plugins: [
      BaseBoldPlugin,
      BaseItalicPlugin,
      BaseH1Plugin,
      BaseH2Plugin,
      BaseH3Plugin,
      BaseBlockquotePlugin,
    ],
    value,
  });

  // Extract text content
  const textContent = editor.api.string([]);
  console.debug('Extracted Text:', textContent);

  // Transform all H1s to H2s
  editor.tf.setNodes(
    { type: 'h2' },
    { at: [], match: (n) => n.type === 'h1' }
  );

  // Add a new paragraph at the end
  editor.tf.insertNodes(
    [{ type: 'p', children: [{ text: 'Added by Node.js script!' }] }],
    { at: [editor.children.length] }
  );

  return {
    textContent,
    transformedValue: editor.children,
  };
}

// Example usage
const mySlateValue = [
  { type: 'h1', children: [{ text: 'Original Document Title' }] },
  { type: 'p', children: [{ text: 'Some paragraph content.' }] },
  {
    type: 'p',
    children: [
      { text: 'Text with ' },
      { text: 'bold', bold: true },
      { text: ' formatting.' },
    ],
  },
];

processDocument(mySlateValue).then(result => {
  console.debug('Processing complete:', result);
});

Available APIs

editor.api: Access various utility functions for querying the editor state:
- editor.api.nodes({ at: [], match }): Find specific nodes
- editor.api.string([]): Extract text content
- HTML Serialization
- Markdown Serialization
editor.tf: Use transform functions to modify the editor content:
- editor.tf.insertNodes(nodes, opts): Insert new nodes
- editor.tf.removeNodes(opts): Delete nodes
- editor.tf.setNodes(props, opts): Update properties of existing nodes
- editor.tf.normalize({ force: true }): Normalize the editor

</Steps>

Next Steps

With Plate configured in your Node.js environment, you can now:

Build Content Pipelines: Create scripts for migrating content from other systems into Plate format
Bulk Operations: Perform bulk updates or transformations on your existing Plate documents
Data Extraction: Validate content structure or extract specific data from your documents
Backend Integration: Integrate with other backend services for content processing pipelines
Static Generation: Explore Markdown Serialization, HTML Serialization, and PlateStatic for generating static content