Installation Troubleshooting

Common issues and solutions when installing and using the Extended Markdown ADF Parser.

Module System Issues

"Cannot use import statement outside a module"

This package supports both CommonJS and ES Modules. Choose the approach that works for your environment:

Solution 1: Use CommonJS (Easiest)

const { Parser } = require('extended-markdown-adf-parser');

Solution 2: Enable ES Modules in package.json

{
  "type": "module"
}

Then use:

import { Parser } from 'extended-markdown-adf-parser';

Solution 3: Use .mjs file extension

mv script.js script.mjs

Solution 4: Use dynamic import in CommonJS

const { Parser } = await import('extended-markdown-adf-parser');

"require() of ES modules is not supported"

This error occurs when trying to use require() on an ES module. Since this package supports both formats, use the appropriate import method:

Solution:

// Instead of: const { Parser } = require('extended-markdown-adf-parser/index.mjs'); // ❌
const { Parser } = require('extended-markdown-adf-parser'); // ✅

Mixed Module Systems

If you're mixing CommonJS and ES Modules in the same project:

// In CommonJS files (.js with no "type": "module")
const { Parser } = require('extended-markdown-adf-parser');

// In ES Module files (.mjs or .js with "type": "module")
import { Parser } from 'extended-markdown-adf-parser';

"Module not found" in TypeScript

Solution: Check your tsconfig.json module resolution:

{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}

Performance Issues with Large Documents

Solution: Use the streaming parser:

import { StreamingParser } from 'extended-markdown-adf-parser';

const streamingParser = new StreamingParser({
  chunkSize: 1000
});

const result = await streamingParser.parseAsync(largeMarkdown);

Volta Version Management Issues

If you're having trouble with Volta automatically switching versions:

Check Volta Configuration:

# Verify Volta is installed
volta --version

# Check pinned versions in project
volta list

# Re-pin versions if needed
volta pin node@20.11.1
volta pin yarn@4.7.0

Restart Shell:

# Restart your shell session
exec $SHELL

# Or source your profile
source ~/.bashrc  # or ~/.zshrc

Package Installation Failures

Network/Registry Issues

Solution 1: Clear npm cache

npm cache clean --force
yarn cache clean

Solution 2: Use different registry

npm install extended-markdown-adf-parser --registry https://registry.npmjs.org/

Permission Issues

Solution 1: Use npx for global installs

npx extended-markdown-adf-parser --version

Solution 2: Fix npm permissions (Unix/macOS)

# Create global directory for npm
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
source ~/.profile

TypeScript Compilation Errors

Missing Type Definitions

The package includes built-in TypeScript definitions, but if you encounter issues:

# Verify TypeScript version compatibility
npx tsc --version

# Check if types are properly resolved
npx tsc --traceResolution | grep extended-markdown-adf-parser

Module Resolution Issues

Update your tsconfig.json:

{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "resolveJsonModule": true
  }
}

ESM/CommonJS Compatibility

Mixing Module Systems

Error: require() of ES modules is not supported

Solution: Use dynamic imports consistently:

// Instead of mixing require and import
const parser = require('extended-markdown-adf-parser'); // Wrong

// Use dynamic import
const { Parser } = await import('extended-markdown-adf-parser'); // Correct

Jest Testing Issues

For Jest testing with ESM:

jest.config.js:

export default {
  preset: 'ts-jest/presets/default-esm',
  extensionsToTreatAsEsm: ['.ts'],
  moduleNameMapping: {
    '^(\\.{1,2}/.*)\\.js$': '$1',
  },
  transform: {
    '^.+\\.tsx?$': ['ts-jest', {
      useESM: true
    }]
  }
};

Memory Issues with Large Files

Heap Out of Memory

Solution: Increase Node.js memory limit

node --max-old-space-size=4096 your-script.js

Use Streaming Parser

import { StreamingParser } from 'extended-markdown-adf-parser';

const streamingParser = new StreamingParser({
  chunkSize: 500,
  enableGarbageCollection: true
});

Getting Help

If you encounter installation issues not covered here:

• Report Issues

• Documentation

• Discussions

Information to Include

When reporting installation issues, please include:

• Node.js version (node --version)

• npm/Yarn version

• Operating system and version

• Complete error messages

• Package.json configuration

• Steps to reproduce the issue

Environment Debugging

System Information:

# Node.js and npm versions
node --version && npm --version

# Operating system
uname -a  # Unix/macOS
systeminfo  # Windows

# Check PATH and environment
echo $PATH
env | grep -i node

Package Information:

# Check installed version
npm list extended-markdown-adf-parser

# Check package dependencies
npm ls --depth=0

# Verify package integrity
npm audit

Recent TypeScript Improvements (v1.2.1+)

If you were experiencing TypeScript compilation errors with earlier versions, these issues have been resolved in recent updates:

Fixed Type Issues

• MediaNode alt property: The MediaNode interface now properly includes the optional alt attribute

• ValidationError line property: The ValidationError interface now includes the optional line property for better error reporting

• Metadata comments: Fixed Data interface extension for ADF metadata handling

• AJV validator types: Improved type safety for schema validation functions

Upgrading from Earlier Versions

If you're upgrading from versions prior to 1.2.1 and experiencing TypeScript errors:

# Update to the latest version
npm update extended-markdown-adf-parser

# Clear TypeScript cache if using tsc
rm -rf node_modules/.cache
npx tsc --build --clean

# Rebuild your project
npm run build

These fixes ensure full TypeScript compatibility without any compilation errors.