#Parsing /parse

import {
  createWikiparser,
  parseWikitext,
  createWikitextParser,
  WikitextParseError,
  DEFAULT_MAX_SOURCE_LENGTH,
} from "react-wikitext/parse";

/parse loads the default parser (the wikiparser-node@1.48.1 browser bundle) and does not load React. Parsing is synchronous.

#parseWikitext

const document = parseWikitext(source, {
  pageName: "Example",
  retainSyntax: false,
});

Uses the shared parser with default configuration; suitable for one-off parsing and simple scenarios.

#createWikiparser

const parser = createWikiparser({
  config: MEDIAWIKI_CONFIG,
  defaults: { pageName: "Example" },
});

const document = parser.parse(source, { maxSourceLength: 50_000 });

• The default config is MEDIAWIKI_CONFIG, a snapshot of the wikiparser-node@1.48.1 site configuration.
• Configuration is deep-cloned and normalized when the factory is created; later mutations of the original object do not affect the parser.
• Changing config requires creating a new parser.
• The library does not export a minimum config. For custom config, copy the default and adjust fields.

#Parse options

interface WikitextParseOptions {
  pageName?: string;
  maxSourceLength?: number; // default 100_000
  maxSyntaxNodes?: number; // default 50_000
  maxSemanticNodes?: number; // default 50_000
  maxDepth?: number; // default 1_000
  retainSyntax?: boolean; // default false
}

Effective budgets merge in this order: per-call options → factory defaults → shared defaults. CRLF / CR is normalized to LF before parsing, and budgets are checked after normalization.

retainSyntax significantly increases memory and build cost; enable it only for source positions or the playground syntax tree.

#Returned document

interface WikitextDocument {
  source: string;
  ast: WikitextRoot;
  syntax?: WikitextSyntaxRoot;
  meta: WikitextDocumentMeta;
  diagnostics: WikitextDiagnostic[];
}

meta contains:

• parser / parserVersion.
• pageName.
• astSchemaVersion and optional syntaxSchemaVersion.
• sourceNormalized, originalLength, and retainSyntax.

The same source with a different config or pageName can produce a different AST; those are parse inputs, not render options.

#Custom adapter

createWikitextParser does not load the default IIFE, which makes it suitable for other parsers:

import { createWikitextParser, type WikitextParserAdapter } from "react-wikitext/parse";

const adapter: WikitextParserAdapter = {
  name: "my-parser",
  version: "1.0.0",
  parse(source, context) {
    // Must return a plain object matching WikitextSyntaxRoot.
    // Ranges are based on LF-normalized source, 1-based line/column + 0-based offset.
    return buildSyntaxRoot(source, context);
  },
};

const parser = createWikitextParser(adapter, {
  defaults: { pageName: "Example" },
});

• The adapter only maps source → syntax tree; normalization, budget merging, semantic AST construction, diagnostics, and meta are handled by the factory.
• context.limits provides the effective maxSyntaxNodes and maxDepth so adapters can stop early.
• The factory still validates structure, ranges, and budgets after the adapter returns.
• The adapter's name / version are written to document meta.

#Errors

class WikitextParseError extends WikitextError {
  constructor(
    code:
      | "SOURCE_TOO_LONG"
      | "SOURCE_TOO_COMPLEX"
      | "INVALID_CONFIG"
      | "PARSE_FAILED"
      | "PARSER_UNAVAILABLE",
    message: string,
    options?: { cause?: unknown },
  );
}

Node and depth limits are internal guardrails. The effective values appear in error.message when triggered and are not exported as constants.

#Related

• Querying, serialization, and node types are in /ast.
• Config constants are in /configs.
• For workers or caching, parse in a worker and serialize the result back.