Skip to content

Add WASM bindings using wasm-bindgen #185

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
Open

Conversation

jp-knj
Copy link

@jp-knj jp-knj commented Aug 11, 2025

Overview

Provides minimal WebAssembly bindings for markdown-rs, addressing the WASM hanging issues mentioned in #182 while following maintainer preference for WASM-only approach (no NAPI).

Background

This PR takes a different approach from #182

  • Prev PR: NAPI + WASM hybrid with platform-specific builds
  • This PR: Pure WASM solution, simpler and more maintainable

Key Improvements

  • Fixes WASM hanging - Resolves the hanging issue reported in Add npm package using napi-rs #182
  • No NAPI complexity - Pure WASM
  • ESM-first - Uses .mjs extension for proper Node.js module resolution
  • Minimal footprint - Single wasm binary (~500KB) vs multiple platform builds

Implementation

import { toHtml, toHtmlWithOptions } from 'markdown-wasm';

// CommonMark
const html = await toHtml('# Hello World');

// With GFM/MDX
const gfmHtml = await toHtmlWithOptions('~text~', { gfm: true });

Why Pure WASM?

Per maintainer feedback on #182:

  • Lower maintenance burden (no per-platform builds)
  • Universal compatibility (one binary for all)
  • No native toolchain requirements
  • Simpler CI/CD pipeline

Testing

  • Works on Node.js 16+, Bun 1.1+
  • No hanging issues
  • Comprehensive test suite included
  • Examples for basic and advanced usage

Performance

While NAPI may be faster, WASM provides:

  • Consistent performance across platforms
  • No native compilation for users
  • Adequate speed for most use cases

This approach prioritizes maintainability and reliability over maximum performance, aligning with project goals.

Related to #182

jp-knj added 5 commits August 15, 2025 00:10
- Add wasm-bindgen setup with Cargo.toml
- Implement to_html and to_html_with_options APIs
- Support CommonMark, GFM, MDX, and frontmatter
- Create async/sync JavaScript API wrapper
- Configure package.json with .mjs build script
- Handle WASM initialization and module loading
- Test basic markdown conversions
- Test GFM, MDX, and security options
- Test sync/async APIs
- Cover edge cases and complex markdown
- Add comprehensive README with API documentation
- Add basic usage example
- Add advanced options example
- Include MIT LICENSE file
- Add wasm to Cargo workspace
- Setup pnpm workspace with wasm directory
- Add root package.json for development scripts
- Update .gitignore for WASM build artifacts
@jp-knj jp-knj marked this pull request as ready for review August 14, 2025 15:29
@wooorm wooorm mentioned this pull request Aug 14, 2025
3 tasks
@wooorm
Copy link
Owner

wooorm commented Aug 14, 2025

Thanks for working on this!
Could we do with plain npm?
should it be called markdown-rs-wasm, what about markdown-wasm? Something else?

- Scope package as @wooorm/markdown-wasm
- Export lib/index.mjs (+ types)
- Add examples script and require Node >=18
- Update Whitelist files

Refs: wooorm#185
@jp-knj
Copy link
Author

jp-knj commented Aug 15, 2025

I’m not fully confident in this change.
does it look good to you? Happy to adjust if needed.

@ChristianMurphy
Copy link
Collaborator

I haven't had a chance to pull down the code and try it out (traveling presently).
But at an approach/strategy level, I'm a lot more comfortable with a single WASM build, over half a dozen single platform builds with N-API bindings.

- Add @wooorm/markdown-wasm
- Update wasm/README.md with correct package name
- Fix installation and import examples to use @wooorm/markdown-wasm
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants