{"id":13087,"library":"drafter","title":"Drafter NPM Package","description":"Drafter is a Node.js wrapper around the API Blueprint parser. It provides both synchronous and asynchronous parsing capabilities for API Blueprint documents, converting them into a machine-readable Abstract Syntax Tree (AST). The package prioritizes the faster C++ binding, Protagonist, but includes a pure JavaScript fallback, drafter.js, if the C++ binding fails to install or load. The current stable version is 2.0.0. The project maintains an active development status with updates typically driven by upstream changes in the core Drafter C++ parser and its JavaScript counterparts, which influences its release cadence. Its key differentiator is its robust handling of API Blueprint parsing, providing a consistent API across potentially different underlying parser implementations.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/apiaryio/drafter-npm","tags":["javascript"],"install":[{"cmd":"npm install drafter","lang":"bash","label":"npm"},{"cmd":"yarn add drafter","lang":"bash","label":"yarn"},{"cmd":"pnpm add drafter","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Primary C++ binding for faster parsing of API Blueprints. Installation is optional as a fallback to drafter.js exists.","package":"protagonist","optional":true},{"reason":"Pure JavaScript fallback parser for API Blueprints, used if protagonist (C++ binding) cannot be installed or loaded.","package":"drafter.js","optional":true}],"imports":[{"note":"The package primarily exports a CommonJS module with `parse` and `parseSync` methods. For ESM, use `import * as drafter from 'drafter';` to access its properties.","wrong":"import drafter from 'drafter';","symbol":"drafter","correct":"import * as drafter from 'drafter';"},{"note":"This is the recommended and documented way to import the library in CommonJS environments.","symbol":"drafter (CommonJS)","correct":"const drafter = require('drafter');"},{"note":"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.","wrong":"import { parse, parseSync } from 'drafter';","symbol":"parse, parseSync","correct":"import { parse, parseSync } from 'drafter'; // (Not officially supported but might work with bundlers)\n// or for robust ESM:\nimport * as drafter from 'drafter';\nconst parse = drafter.parse;\nconst parseSync = drafter.parseSync;"}],"quickstart":{"code":"const drafter = require('drafter');\n\nconst apiBlueprint = `# My API\n# GET /message\n+ Response 200 (text/plain)\n\tHello World\\n`;\n\nconst options = {\n  generateSourceMap: true,\n  requireBlueprintName: false,\n};\n\n// Asynchronous parsing\ndrafter.parse(apiBlueprint, options, (err, result) => {\n  if (err) {\n    console.error('Asynchronous parsing error:', err.message);\n    return;\n  }\n  console.log('Asynchronous parse result:', JSON.stringify(result, null, 2));\n});\n\n// Synchronous parsing\ntry {\n  const resultSync = drafter.parseSync(apiBlueprint, options);\n  console.log('Synchronous parse result:', JSON.stringify(resultSync, null, 2));\n} catch (err) {\n  console.error('Synchronous parsing error:', err.message);\n}","lang":"javascript","description":"This quickstart demonstrates both asynchronous and synchronous parsing of an API Blueprint string, including how to pass options like `generateSourceMap`."},"warnings":[{"fix":"Update 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.","message":"Version 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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure 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.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If 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.","message":"While `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.","severity":"gotcha","affected_versions":"Potentially all versions on newer Node.js runtimes"},{"fix":"Only 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).","message":"The `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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `npm install drafter` in your project directory.","cause":"The 'drafter' package was not installed or is not resolvable in the current Node.js environment.","error":"Error: Cannot find module 'drafter'"},{"fix":"Install 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`.","cause":"The native C++ module `Protagonist` (a dependency of `drafter`) failed to compile, likely due to missing build tools or an incompatible Node.js version.","error":"node-gyp rebuild failed"},{"fix":"For CommonJS, ensure `const drafter = require('drafter');` is used. For ESM, use `import * as drafter from 'drafter';` and then call `drafter.parse()` or `drafter.parseSync()`.","cause":"The `drafter` object was not correctly imported, or the function name is misspelled.","error":"TypeError: drafter.parse is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}