Установка и подключение: npm, CDN, ES-модули, CommonJS

TweetNaCl.js представляет собой компактную реализацию криптографической библиотеки NaCl (Networking and Cryptography library), адаптированную для JavaScript. В экосистеме встречается также обозначение nacl.js, однако чаще используется именно пакет tweetnacl и его дополнительные утилиты.

Основные сценарии использования связаны с браузерной криптографией и Node.js-средой: шифрование, подпись сообщений, генерация ключей, работа с публичной криптографией без зависимостей от нативных модулей.

Наиболее распространённый способ подключения — установка через npm. Библиотека разделена на ядро и вспомогательные утилиты для работы с форматами данных.

Установка базового пакета:

npm install tweetnacl

Дополнительный пакет для преобразования строк и бинарных данных:

npm install tweetnacl-util

Использование в CommonJS-среде Node.js:

const nacl = require("tweetnacl");
nacl.util = require("tweetnacl-util");

В современных сборщиках (Webpack, Vite, Rollup) подключение аналогично, но чаще применяется ES Modules-синтаксис.

ES Modules (import / export)

В среде, поддерживающей ES Modules (современные браузеры, Node.js ESM, Vite, Deno-подобные сборки), используется импорт:

import nacl from "tweetnacl";
import naclUtil from "tweetnacl-util";

Некоторые сборки требуют явного обращения к утилитам:

const message = naclUtil.decodeUTF8("hello");
const keyPair = nacl.box.keyPair();

TweetNaCl.js полностью совместим с ESM благодаря своей структуре без побочных эффектов и минимальной зависимости от окружения.

CommonJS (require)

В старых проектах Node.js или при использовании CommonJS-конфигурации применяется классический require.

const nacl = require("tweetnacl");
const naclUtil = require("tweetnacl-util");

Особенность этой схемы заключается в том, что библиотека поставляется как UMD-совместимый модуль, поэтому корректно работает в большинстве сборок без дополнительной конфигурации транспайлеров.

CDN (браузер без сборки)

Для прямого подключения в браузере без инструментов сборки используется CDN. Подходит для прототипов, учебных проектов и простых страниц.

Подключение через jsDelivr:

<script src="https://cdn.jsdelivr.net/npm/tweetnacl@1.0.3/nacl.min.js"></script>

Дополнительный модуль утилит:

<script src="https://cdn.jsdelivr.net/npm/tweetnacl-util@0.15.1/nacl-util.min.js"></script>

После подключения библиотека становится доступна через глобальный объект:

const keyPair = nacl.box.keyPair();
const encoded = nacl.util.encodeUTF8("data");

Аналогичный вариант через unpkg:

<script src="https://unpkg.com/tweetnacl@1.0.3/nacl.min.js"></script>

Использование в браузерных сборках (Webpack, Vite, Rollup)

При работе через сборщики модулей библиотека устанавливается через npm и импортируется напрямую. Благодаря отсутствию нативных зависимостей она не требует polyfill-ов.

Пример использования в модульной архитектуре:

import nacl from "tweetnacl";

const keyPair = nacl.box.keyPair();

В некоторых конфигурациях Webpack может потребоваться настройка режима совместимости модулей:

resolve: {
  fallback: {
    crypto: false
  }
}

Однако в большинстве современных окружений это не требуется.

Особенности подключения в разных окружениях

В Node.js библиотека работает без ограничений, так как использует чистую JavaScript-реализацию криптографических алгоритмов.

В браузере важно учитывать, что TweetNaCl.js не зависит от WebCrypto API, что обеспечивает одинаковое поведение во всех средах, включая старые браузеры.

При использовании CDN важно следить за порядком подключения:

  • сначала tweetnacl
  • затем tweetnacl-util, если требуется работа со строками

Разделение tweetnacl и tweetnacl-util

Ядро библиотеки (tweetnacl) работает исключительно с Uint8Array. Все операции — шифрование, подписи, генерация ключей — используют бинарные данные.

Пакет tweetnacl-util добавляет вспомогательные функции:

  • encodeUTF8
  • decodeUTF8
  • encodeBase64
  • decodeBase64

Пример:

const message = naclUtil.decodeUTF8("secure message");
const encrypted = nacl.secretbox(message, nonce, key);

Подключение в TypeScript-проектах

Типы обычно устанавливаются отдельно:

npm install --save-dev @types/tweetnacl

После этого импорт работает стандартным образом:

import nacl from "tweetnacl";

Некоторые проекты обходятся без типов, используя встроенную типизацию через Uint8Array.

Различия между npm и CDN-подключением

npm-подключение ориентировано на сборочные системы и серверные приложения, обеспечивая:

  • tree-shaking
  • модульность
  • контроль версий
  • интеграцию с TypeScript

CDN-вариант ориентирован на:

  • отсутствие сборки
  • быстрые прототипы
  • прямую работу в браузере

Работа в Node.js без дополнительных зависимостей

TweetNaCl.js не требует нативных криптографических модулей Node.js. В отличие от crypto, библиотека реализует алгоритмы полностью на JavaScript.

Пример генерации ключевой пары:

const nacl = require("tweetnacl");

const keyPair = nacl.box.keyPair();

console.log(keyPair.publicKey);
console.log(keyPair.secretKey);

Подключение в гибридных окружениях

В проектах, где код выполняется и в браузере, и на сервере, используется единый импорт через npm:

import nacl from "tweetnacl";

Такой подход обеспечивает одинаковое поведение криптографических операций во всех средах, поскольку библиотека не зависит от платформенных API.

Инициализация утилит и расширений

При использовании tweetnacl-util расширение обычно выполняется вручную:

import nacl from "tweetnacl";
import * as naclUtil from "tweetnacl-util";

nacl.util = naclUtil;

Это позволяет сохранять доступ к функциям кодирования в едином пространстве имен.

Подключение в старых браузерах

При использовании CDN в устаревших браузерах библиотека работает без транспиляции, так как код уже поставляется в ES5-совместимом формате UMD.

<script src="https://cdn.jsdelivr.net/npm/tweetnacl/nacl.min.js"></script>

Совместимость модулей

TweetNaCl.js поддерживает несколько форматов загрузки:

  • ES Modules (import)
  • CommonJS (require)
  • UMD (через CDN)

Такая структура позволяет использовать библиотеку практически в любой JavaScript-среде без адаптации к конкретной системе модулей.

Оглавление