Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
drafter
✓ import * as drafter from 'drafter';
✗ import drafter from 'drafter';
The package primarily exports a CommonJS module with `parse` and `parseSync` methods. For ESM, use `import * as drafter from 'drafter';` to access its properties.
drafter (CommonJS)
✓ const drafter = require('drafter');
This is the recommended and documented way to import the library in CommonJS environments.
parse, parseSync
✓ import { parse, parseSync } from 'drafter'; // (Not officially supported but might work with bundlers)
// or for robust ESM:
import * as drafter from 'drafter';
const parse = drafter.parse;
const parseSync = drafter.parseSync;
✗ import { parse, parseSync } from 'drafter';
While some bundlers might allow direct named imports, the package's primary export pattern via CommonJS means accessing properties from the imported object (e.g., `drafter.parse`) is the most reliable method for both CJS and ESM with a wildcard import.
This quickstart demonstrates both asynchronous and synchronous parsing of an API Blueprint string, including how to pass options like `generateSourceMap`.
const drafter = require('drafter');
const apiBlueprint = `# My API
# GET /message
+ Response 200 (text/plain)
Hello World\n`;
const options = {
generateSourceMap: true,
requireBlueprintName: false,
};
// Asynchronous parsing
drafter.parse(apiBlueprint, options, (err, result) => {
if (err) {
console.error('Asynchronous parsing error:', err.message);
return;
}
console.log('Asynchronous parse result:', JSON.stringify(result, null, 2));
});
// Synchronous parsing
try {
const resultSync = drafter.parseSync(apiBlueprint, options);
console.log('Synchronous parse result:', JSON.stringify(resultSync, null, 2));
} catch (err) {
console.error('Synchronous parsing error:', err.message);
}
Debug
Known issues
breakingVersion 2.0.0 is a major breaking change due to upgrades in its underlying parsers, Protagonist (v2.0.0) and Drafter.js (v3.0.0). The output structure of the parsing function has changed significantly. The parsed result is now wrapped in a `parseResult` key, and the `annotations` key is now an array of `annotation` objects instead of a single object.fixUpdate code that processes the parsed AST to expect the new `parseResult` wrapper and the `annotations` array structure. Refer to the release notes of Drafter.js 3.0.0 and Protagonist 2.0.0 for detailed changes.
affects: >=2.0.0
gotchaThe package uses a C++ binding (`Protagonist`) for performance, with `drafter.js` (pure JavaScript) as a fallback. If C++ compilation fails during installation (e.g., missing build tools like `node-gyp`), `drafter` will silently fall back to the slower JavaScript version, potentially leading to unexpected performance degradation.fixEnsure your environment has the necessary build tools for C++ compilation (e.g., `python`, `make`, `C++ compiler`) if consistent high performance is critical. Check `npm install` output for `node-gyp` errors if performance is lower than expected.
affects: All versions
gotchaWhile `drafter` specifies `"node": ">= 4"` in its engines, native Node.js modules (like `Protagonist`) can experience compatibility issues with newer Node.js versions, often requiring specific compiler versions or updates to `node-gyp` or the native module itself.fixIf encountering `node-gyp` or compilation errors on newer Node.js versions, check the `Protagonist` and `node-gyp` GitHub repositories for known issues or required workarounds. Consider using an LTS Node.js version if stability is paramount.
affects: Potentially all versions on newer Node.js runtimes
gotchaThe `generateSourceMap` option adds source map information to the parse result. While useful for debugging, it can increase the size and complexity of the output, which might not be desirable for production environments where only the core AST is needed.fixOnly enable `generateSourceMap: true` during development or if source map integration is specifically required for your application. For production, set it to `false` (which is the default).
affects: All versions
Errors
Common errors & fixes
Error: Cannot find module 'drafter'
The 'drafter' package was not installed or is not resolvable in the current Node.js environment.
fixRun `npm install drafter` in your project directory.
node-gyp rebuild failed
The native C++ module `Protagonist` (a dependency of `drafter`) failed to compile, likely due to missing build tools or an incompatible Node.js version.
fixInstall required build tools: On Windows, use `npm install --global windows-build-tools`. On macOS, install Xcode command line tools (`xcode-select --install`). On Linux, install `build-essential` or equivalent development packages. Ensure your Node.js version is compatible with `Protagonist`.
TypeError: drafter.parse is not a function
The `drafter` object was not correctly imported, or the function name is misspelled.
fixFor CommonJS, ensure `const drafter = require('drafter');` is used. For ESM, use `import * as drafter from 'drafter';` and then call `drafter.parse()` or `drafter.parseSync()`. Audit
Dependencies
protagonistoptionalPrimary C++ binding for faster parsing of API Blueprints. Installation is optional as a fallback to drafter.js exists.
drafter.jsoptionalPure JavaScript fallback parser for API Blueprints, used if protagonist (C++ binding) cannot be installed or loaded.