Переход с Node.js

Большинство проектов Node.js работают в Deno без каких-либо изменений. Deno читает ваш package.json, устанавливает и разрешает те же зависимости npm, запускает модули CommonJS и ES, поэтому в большинстве случаев достаточно указать Deno на существующий проект — и всё заработает.

Вы также можете переходить на Deno постепенно: использовать его только как более быстрый менеджер пакетов с заменой без изменения интерфейса для приложения, которое по-прежнему запускается в Node, запускать существующие скрипты package.json с помощью deno task или переключиться на Deno в качестве среды выполнения и воспользоваться встроенным набором инструментов. В этом руководстве описан каждый этап.

Используйте Deno как менеджер пакетов

Deno полностью совместим с npm и package.json, поэтому проще всего начать с управления зависимостями, не меняя способ запуска кода. deno install читает существующий package.json, разрешает те же пакеты npm и создаёт каталог node_modules, как и npm install:

cd my-node-app
deno install

Теперь вы можете продолжать запускать приложение с Node и использовать Deno только как более быстрый и безопасный менеджер пакетов. Deno читает зависимости как из package.json, так и из deno.json. Полное соответствие команд, различия в работе Deno (скрипты жизненного цикла, аудит, файлы блокировки) и известные нюансы описаны в руководстве по используемому вами менеджеру пакетов: npm, Yarn, pnpm или Bun.

Запустите проект с помощью Deno

Чтобы запустить существующий проект Node с помощью Deno, установите его зависимости и запустите точку входа:

cd my-node-app
deno install
deno run main.js

Сразу заметно одно отличие от Node: в Deno по умолчанию включена безопасность, поэтому при первом обращении приложения к сети, файловой системе или окружению Deno запросит разрешение. Заранее предоставьте приложению необходимые разрешения с помощью флагов (deno run -N -R -E main.js) либо при миграции запустите его с -A, чтобы поведение соответствовало Node, а позднее ограничьте разрешения. Полный список флагов см. в разделе Разрешения.

Если в вашем package.json определены скрипты, запускайте их с помощью deno task — аналога npm run:

{
  "name": "my-project",
  "scripts": {
    "start": "node server.js"
  }
}

deno task start

Большая часть кода будет работать без изменений. Главное — понять, как Deno определяет, является ли файл модулем CommonJS или ES, — это зависит от вашего package.json. Об этом рассказывается далее.

CommonJS и модули ES

Deno запускает модули ES и CommonJS и определяет, как обрабатывать файл, по тем же правилам, что и Node.js:

• Файл .cjs — это всегда CommonJS, а файл .mjs — это всегда модуль ES. Достаточно расширения.
• Файл .js, .ts, .jsx или .tsx загружается как CommonJS, если ближайший package.json задаёт "type": "commonjs", и как модуль ES в противном случае. Deno ищет этот package.json, поднимаясь по дереву каталогов, как и Node.

{
  "type": "commonjs"
}

Поэтому существующий проект CommonJS продолжит работать: при наличии "type": "commonjs" в package.json файлы .js на основе require() запускаются и в Node, и в Deno. Для кода CommonJS зависимости должны присутствовать в node_modules (задайте "nodeModulesDir": "auto" в deno.json), также понадобятся обычные флаги разрешений.

Можно также сочетать обе системы модулей: require() доступен в файлах .cjs или через createRequire, require() в Deno может загружать синхронные модули ES, а из модулей ES можно import файлы CommonJS. Подробности и особые случаи описаны в разделе Поддержка CommonJS.

Распространённые ошибки и способы их устранения

Несколько ошибок, с которыми чаще всего сталкиваются проекты Node при первом запуске, и их значение:

• NotCapable: Requires read access to "...", run again with the --allow-read flag: сработала песочница разрешений. Предоставьте указанное разрешение (здесь — -R) или используйте -A, пока не будете готовы точнее ограничить разрешения.
• ReferenceError: require is not defined: Deno посчитал файл модулем ES. Задайте "type": "commonjs" в package.json или переименуйте файл в .cjs. См. раздел CommonJS и модули ES выше.
• Не удаётся найти модуль / отсутствует node_modules: выполните deno install. Если для работы ваших инструментов нужен каталог node_modules, задайте "nodeModulesDir": "auto" в deno.json.
• Скрипт install/postinstall зависимости не запустился (нативные дополнения, сборки node-gyp): Deno по умолчанию не запускает скрипты жизненного цикла npm. Разрешите их для отдельных пакетов с помощью deno install --allow-scripts=npm:<pkg> или управляйте разрешениями через deno approve-scripts.
• Поведение API node: отличается или API отсутствует: проверьте список совместимости API Node, чтобы узнать состояние поддержки и известные ограничения.

Если вы переносите приложение на базе фреймворка (Next.js, SvelteKit, Nuxt и другие), большинство таких приложений запускаются в Deno, если заменить npm run dev на deno task dev. Пошаговые инструкции для разных фреймворков см. в разделах Веб-разработка и руководствах.

Шпаргалка по переходу с Node на Deno

В проектах Node многие из этих инструментов устанавливаются и настраиваются как отдельные пакеты: eslint, prettier, jest, ts-node, nodemon, nyc, tsc. В Deno всё это доступно в одном исполняемом файле — без дополнительных зависимостей и конфигурационных файлов. Вы можете оставить существующий package.json или перенести конфигурацию в deno.json.

Продолжить изучение

• Совместимость с Node.js и npm. Что поддерживается (встроенные модули node:, пакеты npm, глобальные переменные) и какие известны ограничения.
• Список совместимости API Node. Состояние поддержки каждого встроенного модуля node:.
• Перенос tsconfig.json. Сопоставление параметров tsconfig.json с deno.json.