На этой странице

Node-API — это стабильный C API, встроенный в Node.js, позволяющий C/C++-коду создавать, читать и манипулировать значениями JavaScript так, будто они созданы самим JavaScript. Он появился экспериментально в Node.js 8.0.0 и стал стабильным (перестал быть за флагом) в период Node.js 8/10.

Поскольку Node-API является частью самого Node.js, он не требует дополнительной установки.

До Node-API доминирующим подходом к разработке нативных аддонов был Native Abstractions for Node.js (NAN). NAN работает, вызывая напрямую V8 API, который меняется с каждым мажорным релизом V8. Это значит, что аддоны на основе NAN часто приходится перекомпилировать — а иногда и обновлять — когда Node.js выпускает новую версию V8.

Node-API абстрагирует JavaScript-движок за стабильным интерфейсом. Это даёт вам две важные гарантии:

  1. Обратная совместимость — модуль, собранный сегодня, будет работать на всех будущих версиях Node.js без какой-либо перекомпиляции или изменений кода.
  2. Стабильность ABI — поскольку API ABI-стабилен, скомпилированный бинарник .node сам по себе продолжает работать между релизами Node.js.

Самая частая причина писать нативный аддон — предоставить существующую C/C++-библиотеку JavaScript-разработчикам. Node-API позволяет вам сопровождать свой C/C++-код независимо и синхронизировать JavaScript-биндинги с минимальными усилиями.

Некоторым приложениям — например, построенным на Electron или NW.js — нужен доступ к системным API, которые Node.js не предоставляет. Node-API предоставляет «крючки» (hooks), чтобы дотянуться до этих ресурсов.

Для тяжёлых по вычислениям задач написание «горячего пути» (hot path) на C или C++ и вызов его из JavaScript через Node-API может дать существенный прирост производительности. В отличие от JIT-компилируемого JavaScript, скомпилированный C/C++-бинарник доступен Node.js сразу, без фазы «прогрева» (warm-up).

Важный спутник Node-API — npm-пакет node-addon-api. Он оборачивает C API в идиоматичную объектную модель C++, уменьшая объём шаблонного кода (boilerplate) и делая распространённые паттерны — например, оборачивание C++-объектов в JavaScript-объекты — гораздо эргономичнее. Он сохраняет полную гарантию ABI-стабильности Node-API.

Большинство примеров на этом сайте используют node-addon-api.