Debug

Debug MDXLD applications with browser DevTools, error overlays, and diagnostic tools.

Development Error Overlay

The development server shows clear error messages when something goes wrong:

mdxe dev

Errors are displayed with:

Error Message: Clear description of what went wrong
Stack Trace: Where the error occurred
Code Frame: The code that caused the error
Suggestions: How to fix common issues

Common Errors

Invalid Frontmatter

---
$type: BlogPost
title: Missing Quote
author: Jane Doe"  # ❌ Mismatched quotes
---

Error: YAMLException: bad indentation

Fix: Ensure proper YAML syntax

Type Mismatch

const doc: BlogPost = {
  $type: 'Article',  // ❌ Type mismatch
  title: 'My Post'
}

Error: Type 'Article' is not assignable to type 'BlogPost'

Fix: Use correct $type or union type

Missing Required Fields

---
$type: BlogPost
title: My Post
# ❌ Missing required 'author' field
---

Error: ValidationError: Missing required field 'author'

Fix: Add required fields to frontmatter

Browser DevTools

Inspect MDX Components

Use React DevTools to inspect MDX component props:

<BlogPost>
  $type: "BlogPost"
  title: "My Post"
  author: "Jane Doe"
  datePublished: "2024-01-15"

Debug State

Use console.log to debug document data:

import { parse } from 'mdxld'

const doc = parse(mdx)
console.log('Parsed document:', doc)
console.log('Frontmatter:', doc.data)
console.log('Content:', doc.content)

Network Tab

Debug API calls to .do platform:

GET https://api.do/blog/my-post
Authorization: Bearer DO_TOKEN

Validation Debugging

Debug validation errors:

import { validate } from 'mdxld'

const result = validate(doc, schema)

if (!result.valid) {
  console.error('Validation errors:')
  result.errors.forEach(err => {
    console.error(`  ${err.path}: ${err.message}`)
    console.error(`    Got: ${JSON.stringify(err.value)}`)
  })
}

Database Debugging

Debug MDX database queries:

import { search } from 'mdxdb'

const results = await search('TypeScript', {
  type: 'BlogPost',
  fuzzy: true
})

console.log(`Found ${results.length} results`)
results.forEach(result => {
  console.log(`  ${result.document.data.title} (score: ${result.score})`)
  result.matches.forEach(match => {
    console.log(`    ${match.field}: ${match.text}`)
  })
})

AI Debugging

Debug AI generation and editing:

import { generate } from 'mdxai'

const mdx = await generate({
  prompt: 'Create a blog post about TypeScript',
  type: 'BlogPost',
  model: 'gpt-5'
})

console.log('Generated MDX:')
console.log(mdx)

Source Maps

Source maps are automatically generated in development mode for debugging TypeScript:

// Your TypeScript code
const doc = parse(mdx)

// ❌ Error occurs here
const title = doc.data.titel  // Typo

// DevTools shows original TypeScript line, not compiled JavaScript

Logging

Enable verbose logging:

DEBUG=mdxe:* mdxe dev
DEBUG=mdxdb:* mdxe test
DEBUG=mdxai:* mdxai generate "..."

Performance Debugging

Build Analysis

Analyze bundle size:

mdxe build --analyze

Profile Components

Use React Profiler to find slow components:

import { Profiler } from 'react'

<Profiler id="BlogPost" onRender={(id, phase, duration) => {
  console.log(`${id} (${phase}) took ${duration}ms`)
}}>
  <BlogPost {...props} />
</Profiler>

Remote Debugging

Debug deployed applications:

# Enable source maps in production
mdxe build --sourcemap

# Deploy with debug mode
mdxe deploy --debug

Common Pitfalls

Forgetting $ prefix: Use $type, $context, $id not type, context, id
Invalid YAML: Check indentation and quotes
Type mismatches: Ensure $type matches TypeScript interface
Missing imports: Import from correct package (mdxld, mdxe, mdxai, mdxdb, mdxui)
Async/await: Remember database operations are async

Debug

On this page