micromark Build Tool

Common errors

• Error: Command failed with exit code 1

  cause This generic error often indicates that `micromark-build` could not find the expected `dev/` source directory, or encountered other file system or processing errors during its run.
  fix Verify that your project structure includes a `dev/` folder containing your development source code. Ensure that `micromark-build` and its internal dependencies are correctly installed and accessible in your environment (`npm install`). Check for any syntax errors in your source files that might halt the Babel transformation.

• Error: Cannot find module 'micromark-build' from '...' or 'TypeError: micromarkBuild is not a function'

  cause These errors occur when attempting to `import` or `require` `micromark-build` directly into your JavaScript/TypeScript code.
  fix As `micromark-build` is a CLI tool, it should not be imported or required as a programmatic module. Instead, execute it from your `package.json` scripts, for example, by adding `"build": "micromark-build"` to your `scripts` section and running `npm run build`.

Warnings

• breaking Projects within the unified collective, including `micromark-build`, are only compatible with maintained versions of Node.js. Major releases typically drop support for unmaintained Node.js versions.
  Fix: Ensure your development environment runs on Node.js v16 or higher. Always consult the `micromark` monorepo's `security.md` for the most up-to-date compatibility requirements before upgrading.
• gotcha micromark-build is a highly specialized tool tailored for the `micromark` ecosystem, specifically for optimizing micromark extensions. It is not a generic JavaScript build tool and is not recommended for use outside this context.
  Fix: Only integrate `micromark-build` into projects developing or extending `micromark` functionality. For other types of JavaScript or TypeScript projects, consider widely-used bundlers or build tools like Webpack, Rollup, or esbuild.
• gotcha To correctly use `micromark-build` and leverage its development-time features (assertions, debug messages), you must define an `exports` map in your `package.json` with a `development` condition. To run your project using the development files, Node.js must be launched with the `--conditions development` flag.
  Fix: Configure your `package.json` with an `exports` field pointing to both `development` (e.g., `./dev/index.js`) and `default` (e.g., `./index.js`) entry points. When developing, run your application or tests with `node --conditions development your-entry-file.js`.

Install

• npm install micromark-build npm
• yarn add micromark-build yarn
• pnpm add micromark-build pnpm

Imports

• micromark-build (CLI)
  wrong:

  import { micromarkBuild } from 'micromark-build'

  correct:

  npm install micromark-build --save-dev
  // Then, in package.json scripts:
  "build": "micromark-build"

  This package is fundamentally a Command Line Interface (CLI) tool and is not intended for direct programmatic JavaScript/TypeScript imports. Its functionality is invoked via command-line execution, typically through an npm script.
• Development Condition
  wrong:

  import { development } from 'micromark-build'

  correct:

  node --conditions development ./dev/index.js

  While `micromark-build` processes files that can be conditionally loaded, the 'development' condition itself is a Node.js runtime flag, not a direct export from this package. Developers configure their project's `exports` map and use this flag to access unoptimized development code.
• TypeScript Types (related)
  wrong:

  import type { BuildOptions } from 'micromark-build'

  correct:

  import type { CompileContext } from 'micromark-util-types'

  `micromark-build` itself is fully typed with TypeScript but explicitly states it exports no *additional* public types for direct import. Any necessary types for developing micromark extensions, which `micromark-build` processes, would typically be imported from other `micromark-util-*` or `micromark-core-*` packages within the ecosystem.

Quickstart

This quickstart illustrates how to configure `micromark-build` in a `package.json` for a micromark extension. It shows how to define `dev/` and production `lib/` entry points using an `exports` map, and provides example development code that `micromark-build` will optimize by removing assertions and debug logs, and inlining constants.

{
  "name": "my-micromark-extension",
  "version": "1.0.0",
  "description": "My custom micromark extension.",
  "type": "module",
  "main": "index.js",
  "scripts": {
    "build": "micromark-build"
  },
  "exports": {
    "development": "./dev/index.js",
    "default": "./index.js"
  },
  "devDependencies": {
    "micromark-build": "^2.0.0",
    "devlop": "^1.0.0",
    "micromark-util-symbol": "^2.0.0",
    "uvu": "^0.5.0"
  }
}

// Example: my-micromark-extension/dev/index.js
// (This file is processed by `micromark-build` into lib/index.js)
import { codes } from 'micromark-util-symbol';
import { assert } from 'uvu/assert';
import { debug } from 'devlop';

const log = debug('my-extension');

export function myExtension() {
  assert.ok(true, 'This assertion will be removed in production!');
  log('Debugging my extension setup.');

  return { tokenizer: { 92: onBackslash } }; // ASCII 92 is '\\'
}

function onBackslash(code) {
  log('Handling backslash character.');
  // `codes.backslash` will be inlined in production by micromark-build.
  return code === codes.backslash ? 1 : 0;
}