mdxe - Zero-Config Executable MDX

mdxe is a lightweight, zero-config CLI tool and build utility designed for MDX files. It offers an effortless way to execute, render, and preview MDX content without the hassle of manual setup.

Features

• Zero Config: Get started immediately without worrying about configuration.
• Multiple Renderers: Support for both React and Hono JSX rendering modes.
• CLI Execution: Evaluate MDX files directly in the console using Ink for a rich, interactive terminal experience.
• Dev Server by Default: Automatically starts a browser-based preview environment powered by Vite alongside the CLI evaluation.
• File Watching: Automatically updates both the CLI and browser preview as you make changes to the MDX file.
• Cloudflare Workers Support: Build and deploy MDX content directly to Cloudflare Workers using Hono JSX.

Installation

Install mdxe globally using npm:

npm install -g mdxe

Or use mdxe via npx without needing to install it globally:

npx mdxe <file.mdx>

Usage

Default Behavior

Run the following command to evaluate and display the MDX content in your terminal and start a development server:

mdxe <file.mdx>

• In the CLI: The MDX content will be rendered in the terminal using Ink.
• In the Browser: The MDX file will be served and watched via a Vite-powered dev server. A URL (e.g., http://localhost:3000) will be logged to the console, allowing you to open the file in your browser.

Both environments will update automatically when changes are made to the MDX file.

Build Static Output

Compile your MDX file into a static site or export it for production:

mdxe build <file.mdx>

The static output will be placed in the dist directory by default.

Command Options

• --port <number>: Specify a custom port for the dev server (default: 3000).
• --out-dir <path>: Set the output directory for the build command (default: dist).
• --open: Automatically open the browser when starting the dev server.
• --watch: Enable file watching for live previews or builds.
• --no-browser: Disable the browser preview, keeping only the CLI evaluation.
• --renderer <type>: Choose the rendering engine ('react' or 'hono', default: 'react').
• --worker-build: Build for Cloudflare Workers deployment (requires Hono renderer).

Examples

Default Execution (React)

mdxe example.mdx

This renders the MDX content in the terminal and starts a live preview server in the browser using React.

Using Hono JSX Renderer

mdxe example.mdx --renderer hono

This uses the Hono JSX renderer for both terminal and browser preview.

Build for Cloudflare Workers

mdxe example.mdx --renderer hono --worker-build

This builds the MDX file for deployment to Cloudflare Workers using Hono JSX.

Start Dev Server with Custom Port

mdxe example.mdx --port 4000 --open

This starts a development server on port 4000 and opens the browser automatically.

Build Static Files

mdxe build example.mdx --out-dir static

This compiles the MDX file into the static directory.

Worker Deployment

When using the --worker-build flag, mdxe will:

1. Process MDX files using the Hono JSX renderer
2. Generate a Cloudflare Workers compatible entry point
3. Bundle all dependencies using esbuild
4. Output the worker files to the specified directory

Example deployment workflow:

# Build the worker
mdxe example.mdx --renderer hono --worker-build --out-dir worker

# Deploy using wrangler
cd worker && wrangler publish

Why MDXE?

• Simplicity: Focus on writing MDX without worrying about build tools.
• Flexibility: Evaluate MDX for terminal-based workflows or run a live preview for web development.
• Modern Tooling: Built on top of Vite for fast, modern development.

Contributing

We welcome contributions! If you have ideas or issues, please feel free to open a GitHub issue or submit a pull request.

License

This project is licensed under the MIT License.

Happy MDX-ing with mdxe! 🚀