npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@ekisu/mdxx

v0.5.2

Published

Render reproducible, interactive HTML from self-describing MDX documents

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

ekisuekisu

Keywords

Readme

mdxx

CLI for rendering reproducible, interactive HTML from self-describing MDX documents. See DESIGN.md for the approved format and rendering contract.

Installation

mdxx requires Bun 1.3.13 or newer. Run it without installing:

bunx @ekisu/mdxx init document.mdx
bunx @ekisu/mdxx run document.mdx

It can also be invoked through npm's package runner when Bun is installed:

npx @ekisu/mdxx init document.mdx
npx @ekisu/mdxx run document.mdx

Install it globally when the shorter mdxx command is preferred:

bun add --global @ekisu/mdxx
mdxx --help

Development

Enter the development environment and install dependencies:

devenv shell
bun install

Run the CLI, tests, or type checker:

bun run start
bun test
bun run check

Document

An mdxx document is ordinary MDX with strict YAML frontmatter:

---
title: Example
mdxx:
  format: 1
---

# Hello

JavaScript and TypeScript components can be declared inline or imported from relative modules. Bare npm imports are resolved in an isolated generated application with explicit React dependencies; local images and CSS are content-addressed in the build output.

GitHub Flavored Markdown is supported, including tables and task lists. Fenced mermaid blocks are rendered as diagrams in the browser. The generated HTML is an initially empty shell, and the document mounts as a conventional client-side React application.

Commands

mdxx init document.mdx
mdxx inspect document.mdx
mdxx verify document.mdx
mdxx lock document.mdx
mdxx unlock document.mdx
mdxx build document.mdx --output dist
mdxx build document.mdx --output dist --replace
mdxx build document.mdx --locked --output dist
mdxx build document.mdx --locked --output dist --replace
mdxx run document.mdx
mdxx run document.mdx --locked
mdxx smoke document.mdx
mdxx smoke document.mdx --locked --browser /path/to/chromium --timeout 10000
mdxx smoke document.mdx --json

build creates <document-name>.html plus content-addressed browser chunks and assets. It refuses to replace an existing output path unless --replace is passed. Replacement builds and validates the complete next tree before changing the destination, so a build failure leaves the previous output unchanged and new HTML is never published before its referenced assets. run performs the same build in a fresh temporary directory and serves it on 127.0.0.1. smoke builds and serves the document, launches Chromium, and fails unless the runtime reaches its mounted state without browser errors or failed requests. Chromium is selected by --browser, then CHROMIUM_PATH, then executable Google Chrome or Chromium apps in /Applications and ~/Applications on macOS, then chromium on PATH; --json emits a structured CI result including the selected browser.

The generated <html> element exposes data-mdxx-state="loading|mounting|mounted|error". Uncaught errors during loading or mounting are fatal: data-mdxx-error and a visible fallback contain the error message, while smoke diagnostics retain the startup phase, stack, and nested causes. After the initial React commit reaches mounted, mdxx removes its global startup listeners; later browser diagnostics follow normal browser handling and do not replace the rendered document or change its mdxx state.

Examples

Each example is an isolated document project:

  • examples/vanilla-graph/document.mdx is a self-contained Markdown-first document with one inline <style> block and one interactive SVG, with no external stylesheet.
  • examples/northstar-microgrid/document.mdx is a complete interactive commissioning dossier with React Flow, custom Visx SVG charts, ECharts Canvas rendering, package fonts, a lazy browser chunk, and a deterministic Worker simulation.
  • examples/project-plan/document.mdx is the earlier multi-file implementation plan.
bun run start run examples/vanilla-graph/document.mdx
bun run start run examples/northstar-microgrid/document.mdx

An embedded lock records the exact Bun lock state, normalized package graph, target, integrity values, and source digest. Locked builds use Bun's frozen lockfile mode and reject graph, target, integrity, or source drift.

Security

Document code is bundled without being imported or evaluated by the build and runs with normal browser authority after client mounting. Built-in modules, remote code imports, computed imports, CommonJS require, and absolute imports are rejected; static dynamic imports are included in the browser output graph.

Loopback serving and browser-origin isolation do not make untrusted document code safe. Use a dedicated browser profile or stronger external sandbox for untrusted documents. See DESIGN.md for the complete format, reproducibility contract, and security boundaries.