@lanexio/parser-grammar-mdx

This page documents @lanexio/parser-grammar-mdx, the MDX grammar package implementing MDX 3.0 — Markdown with JSX and ESM import/export support.

• Version: Stable
• Module name: parser-grammar-mdx
• Package: @lanexio/parser-grammar-mdx
• Import path: @lanexio/parser-grammar-mdx
• Layer: 2 (Grammar)
• Runtime: Universal
• Module format: ESM
• Stability: Stable
• Primary use case: Parse MDX documents (Markdown with JSX) into a flat AST.

Layer contract

Layer 2 dependency rules

This package depends only on Layer 1 core packages. It does not import from query, bridge, devtools, or entry packages. Grammar packs never depend on other grammar packs.

Note: This grammar depends on @lanexio/parser-grammar-markdown as a runtime dependency for delegated Markdown parsing.

When to use this module

• You need to parse MDX documents (Markdown + JSX + ESM) into a traversable AST.
• You need balanced JSX expression scanning for tooling workflows.

Module boundary

Boundary	Description
Inputs	Uint8Array (source bytes) + optional ParseMdxOptions
Outputs	LexTree (flat AST rooted at MdxKind.MdxJsxFlowElement)
Side effects	None
Determinism	Yes
External dependencies	@lanexio/parser-core, @lanexio/parser-grammar-markdown
Never-throw guarantee	Yes
Security surface	None (parse only, no output generation)

Installation

1. Install the package.

   pnpm

   pnpm add @lanexio/parser-grammar-mdx

   npm

   npm install @lanexio/parser-grammar-mdx

   yarn

   yarn add @lanexio/parser-grammar-mdx

2. Import the named export.

   import { parseMdx } from '@lanexio/parser-grammar-mdx';

Peer dependencies

Requirement	Required	Layer	Notes
@lanexio/parser-core	Yes	1	^1.0.0
@lanexio/parser-grammar-markdown	Yes	2	^1.0.0 (delegated Markdown parsing)

Basic Usage

import { parseMdx } from '@lanexio/parser-grammar-mdx';

const encoder = new TextEncoder();
const bytes = encoder.encode('# Hello\n\n<Button>Click</Button>\n\nexport const name = "World"');

const tree = parseMdx(bytes);

console.log(tree.nodeCount);

Strict CommonMark mode

const tree = parseMdx(encoder.encode('# Hello'), { gfm: false });

Exports

Export	Type	Description
parseMdx	(source: Uint8Array, options?: ParseMdxOptions) => LexTree	Parse MDX. Never throws.
scanBalanced	(source: Uint8Array, options?: ScanBalancedOptions) => BalancedRegion[]	Scan for balanced JSX expressions.
MdxKind	const object	Numeric kind IDs for all MDX node types.
MdxField	const object	Numeric field IDs for MDX element slots.
MDX_FIELD_NAMES_BY_ID	readonly string[]	Field name lookup by numeric field ID.
MDX_KIND_NAMES_BY_ID	readonly Record<number, string>	Kind-name lookup by numeric ID.
MdxParseErrorCode	const object	Parse error code constants.
mdxGrammar	LanexioParserPureGrammar	Grammar descriptor for use with parser-pure.
mdxRegistration	GrammarRegistration	Registration for the unified grammar registry.

Options

ParseMdxOptions

Field	Type	Required	Default	Description
gfm	boolean	No	true	Enable GFM extensions in the embedded Markdown parser.

ScanBalancedOptions

Field	Type	Required	Default	Description
(reserved)	-	-	-	Reserved for future extension.

Return shape

Property	Type	Description
root	LexNode	Root node (MdxKind.MdxJsxFlowElement).
nodeCount	number	Total nodes in the tree.
source	Uint8Array	Original parsed bytes.

Exported types

Type	Purpose	Notes
ParseMdxOptions	Options for parseMdx	{ gfm?: boolean }
ScanBalancedOptions	Options for scanBalanced	Reserved
BalancedRegion	Balanced expression region	Returned by scanBalanced
MdxKindType	Union of all MdxKind values	Type-safe kind reference
MdxFieldType	Union of all MdxField values	Type-safe field reference
MdxParseError	Parse error descriptor	Returned via error codes

Configuration and Extension

GFM in MDX

GFM is enabled by default in the embedded Markdown parser. Pass { gfm: false } for strict CommonMark within MDX documents.

Balanced scanning

scanBalanced is a utility for tooling workflows that need to find balanced JSX expressions (braces, parentheses, brackets, angle brackets) in MDX source.

Accessibility

Accessibility requirements

• No direct accessibility surface. The MDX parser produces flat AST data structures.

Accessibility checklist

Concern	Status
Generated output semantics	Not applicable (syntax format)
ARIA attributes in serialized output	Not applicable
Semantic element round-trip	Not applicable

Security

Security considerations

• parseMdx never throws on any byte sequence.

Threat	Mitigation	Status
Malformed input byte sequence	Panic-free guarantee: all inputs accepted, errors produce LexError AST nodes	Implemented

Companion packages

Package	Relationship	Layer	Notes
@lanexio/parser-core	Requires	1	Provides LexTree, LexNode, LexCursor
@lanexio/parser-grammar-markdown	Requires	2	Delegated Markdown parsing
@lanexio/parser	Consumes	6	Unified entry point

Changelog

Version	Date	Status	Notable changes
1.0.0	2026-05-29	Current	Initial stable release. Apache-2.0.

Migration notes

• None.

Related Content

Flat AST How the 16-byte node layout works.

Stability Guarantees Never-throw, panic-free, and 3-token recovery.