Deno и Visual Studio Code

На этой странице рассказывается о разработке приложений Deno с помощью Visual Studio Code и официального расширения vscode_deno.

Установка

Расширение Deno для VS Code интегрируется непосредственно с Deno CLI с помощью протокола языкового сервера. Это помогает гарантировать, что сведения о вашем коде соответствуют тому, как он будет работать при запуске с помощью Deno CLI.

Расширение Deno устанавливается так же, как и другие расширения в VS Code. Найдите Deno на вкладке расширений VS Code и нажмите кнопку установить или перейдите по этой ссылке, чтобы открыть страницу расширения и установить его.

После первой установки расширения вы должны увидеть приветственную страницу. (Если вы пропустили её или хотите увидеть снова, нажмите ⌘ ⇧ P, чтобы открыть палитру команд, и выполните команду Deno: Welcome.)

Включение Deno в рабочей области VS Code

Мы понимаем, что не каждый проект, над которым вы работаете в VS Code, является проектом Deno. По умолчанию в VS Code встроена служба языка TypeScript/JavaScript, которая используется при редактировании файлов TypeScript или JavaScript.

Чтобы получить поддержку API Deno и разрешать модули так же, как это делает Deno CLI, необходимо включить Deno для рабочей области. Самый простой способ сделать это — выбрать команду Deno: Initialize Workspace Configuration в палитре команд VS Code.

Эта команда добавит "deno.enable": true в конфигурацию рабочей области (в корневой каталог рабочей области .vscode/settings.json). После завершения команды появится уведомление об инициализации рабочей области Deno.

Эти и другие параметры доступны на панели параметров VS Code. На панели этот параметр называется Deno: Enable.

Параметры папки рабочей области

Эти параметры можно задать для папки рабочей области. Остальные параметры в настоящее время применяются только ко всей рабочей области:

• deno.enable — определяет, включен ли языковой сервер Deno. Если он включен, расширение отключит встроенные службы языка JavaScript и TypeScript в VS Code и вместо них будет использовать языковой сервер Deno. логическое значение, по умолчанию false
• deno.enablePaths — определяет, включен ли языковой сервер Deno только для указанных путей в папке рабочей области. По умолчанию используется пустой список.
• deno.codeLens.test — определяет, включена ли подсказка для тестов в редакторе кода. логическое значение, по умолчанию true
• deno.codeLens.testArgs — список аргументов, передаваемых в deno test при активации подсказки для тестов в редакторе кода. массив строк, по умолчанию ["--allow-all"]

При включении проекта расширение будет получать сведения непосредственно из установленной версии Deno CLI. Кроме того, расширение отключит встроенное расширение TypeScript/JavaScript.

Частичное включение Deno в рабочей области VS Code

В рабочей области (или папке рабочей области) можно включить Deno для подпутей, оставив код за пределами этих путей без Deno. Для такого кода будет использоваться встроенный языковой сервер JavaScript/TypeScript в VS Code. Используйте параметр Deno: Enable Paths (или deno.enablePaths при ручном редактировании).

Например, если у вас есть проект такой структуры:

project
├── worker
└── front_end

Если вы хотите включить Deno только для пути worker (и его подпутей), добавьте ./worker в список Deno: Enable Paths в конфигурации.

Проекты со смешанной конфигурацией Deno

Эта возможность позволяет создавать проекты со смешанной конфигурацией Deno, в которых для одних папок рабочей области Deno включен, а для других — нет. Это полезно при создании проекта с компонентом интерфейса, для кода которого требуется другая конфигурация.

Для этого создайте новую рабочую область (или добавьте папку в существующую) и в параметрах укажите для одной из папок deno.enable со значением true, а для другой — false. После сохранения конфигурации рабочей области вы увидите, что языковой сервер Deno применяет диагностику только к включенным папкам, а для другой папки встроенный компилятор TypeScript в VS Code будет предоставлять диагностику для файлов TypeScript и JavaScript.

Линтинг

Тот же механизм, который предоставляет диагностику при использовании deno lint, можно использовать и через расширение. Включите параметр Deno: Lint на панели параметров (или deno.lint при редактировании параметров в формате JSON), чтобы редактор начал отображать в коде предупреждения линтера. Дополнительные сведения об использовании линтера Deno см. в разделе «Линтер».

Использование файла конфигурации

Для проекта Deno файл конфигурации не обязателен, но в некоторых случаях он может быть полезен. Если вы хотите применить те же параметры, что и при указании параметра --config в командной строке, можно использовать параметр Deno: Config (или deno.config при ручном редактировании).

Расширение Deno также автоматически обнаруживает и применяет deno.jsonc или deno.json, проверяя наличие файла конфигурации в корневом каталоге рабочей области. Параметр Deno: Config, заданный вручную, переопределяет это автоматическое поведение.

Форматирование

Deno CLI включает встроенный форматтер, который можно запустить с помощью deno fmt, а также настроить для использования в VS Code. Deno должен быть в раскрывающемся списке параметра Editor: Default formatter (при ручном редактировании параметров это будет "editor.defaultFormatter": "denoland.vscode-deno").

Указание пути к Deno CLI

Расширение ищет исполняемый файл Deno CLI в PATH хост-системы, но иногда это нежелательно. В этом случае можно задать параметр Deno: Path (или deno.path при ручном редактировании), указав путь к исполняемому файлу Deno. Если указан относительный путь, он будет разрешен относительно корневого каталога рабочей области.

Подсказки для импорта

При попытке импортировать модуль расширение предложит варианты автодополнения импорта. В подсказки будут включены локальные файлы с относительными путями, а также любые удаленные файлы из кэша.

Расширение поддерживает автоматическое дополнение из реестров: удаленный реестр или сайт модулей может предоставлять метаданные, позволяющие клиенту находить модули. По умолчанию расширение проверяет хосты и источники на поддержку подсказок и, если такая поддержка есть, предлагает включить эту функцию. Изменить это поведение можно, сняв флажок Deno > Suggest > Imports: Auto Discover в параметрах (или deno.suggest.imports.autoDiscover при ручном редактировании).

Отдельные хосты и источники можно включить или отключить, изменив параметр Deno > Suggest > Imports: Hosts — deno.suggest.imports.hosts в соответствующем settings.json.

Кэширование зависимостей

Deno однократно загружает зависимости (пакеты npm и JSR, а также модули с удаленных URL-адресов) и сохраняет их в локальном кэше. При запуске таких команд, как deno run, deno test, deno info или deno install, CLI загружает еще не закэшированные зависимости и помещает их в кэш.

При разработке в редакторе, если зависимость не закэширована, для нее будет показано диагностическое сообщение, например Uncached or missing remote URL: "https://deno.land/x/example/mod.ts". Deno не будет автоматически кэшировать эту зависимость, если только она не была выбрана из подсказки импорта реестра (см. выше).

Помимо запуска команды в командной строке, расширение позволяет кэшировать зависимости прямо в редакторе. Для отсутствующей зависимости будет доступно быстрое исправление, с помощью которого Deno попытается закэшировать зависимость. Чтобы применить исправление, нажмите CTRL . или ⌘ ., когда курсор находится в спецификаторе импорта, либо наведите указатель на спецификатор и выберите Quick Fix....

Кроме того, в палитре команд доступна команда Deno: Cache Dependencies, которая попытается кэшировать все зависимости модуля, открытого в редакторе.

Подсказки в редакторе кода

Языковой сервер поддерживает несколько подсказок в редакторе кода (контекстную информацию с действиями, встроенную в код), которые помогают лучше разобраться в коде. Большинство из них по умолчанию отключены, но их можно легко включить:

Deno > Code Lens: Implementations

deno.codeLens.implementations — добавляет подсказку со списком всех реализаций элемента в других частях кода.

Deno > Code Lens: References

deno.codeLens.references — добавляет подсказку со списком всех ссылок на элемент в других частях кода.

Deno > Code Lens: References All Functions

deno.codeLens.referencesAllFunctions — добавляет подсказку со списком всех ссылок на все функции в коде. Все функции исключены из упомянутого выше параметра References.

Подсказка для тестирования в редакторе кода

Deno CLI включает встроенный API для тестирования, доступный в разделе Deno.test. В расширении и языковом сервере по умолчанию включена подсказка в редакторе кода, позволяющая запускать тесты прямо из редактора.

Когда у вас есть блок кода с тестом:

import { assert } from "jsr:@std/assert@1";

Deno.test({
  name: "a test case",
  fn() {
    let someCondition = true;
    assert(someCondition);
  },
});

Над тестом появится подсказка в редакторе кода:

▶ Run Test

Если нажать на подсказку, расширение запустит Deno CLI для выполнения теста и отобразит результат. В соответствии с другими заданными параметрами расширение попытается запустить тест с теми же настройками. Если нужно изменить аргументы, передаваемые при выполнении deno test, это можно сделать с помощью параметра deno.codeLens.testArgs.

Расширение также попытается определить, если в том же модуле вы деструктурируете функцию Deno.test или присваиваете ее переменной. Поэтому можно написать такой код, и подсказка в редакторе всё равно будет работать:

const { test: denoTest } = Deno;

denoTest({
  name: "example test",
  fn() {},
});

Чтобы отключить эту функцию, сбросьте параметр Deno > CodeLens: Test — deno.codeLens.test.

Запускать тесты можно из представления «Обозреватель тестов», с помощью подсказок в редакторе кода или через палитру команд. Кроме того, в представлении «Обозреватель тестов» можно использовать фильтр, чтобы исключить определенные тесты из запуска.

Если тест завершается с ошибкой, сообщение об ошибке, включая трассировку стека, будет доступно при просмотре результатов теста в VS Code.

Настройка тестов

По умолчанию тесты выполняются примерно так же, как при запуске deno test --allow-all в командной строке. Эти аргументы по умолчанию можно изменить с помощью параметра Deno > Testing: Args в пользовательских параметрах или параметрах рабочей области (или deno.testing.args при ручной настройке). Добавьте сюда отдельные аргументы, которые вы использовали бы с подкомандой deno test.

С учетом других заданных параметров эти параметры будут автоматически объединяться с «командной строкой», используемой при запуске тестов, если только они явно не указаны в параметре Deno > Testing: Args.

Использование отладчика

Расширение интегрируется со встроенным отладчиком VS Code. Чтобы создать конфигурацию, перейдите на панель Run and Debug, нажмите create a launch.json file и выберите Deno из доступных вариантов отладчика. (Созданное type конфигурации будет node — это нормально.)

Отладка проекта, работающего через сервер разработки

Созданная конфигурация Deno запускает один файл точки входа напрямую. Такой способ не подходит для проектов, задача разработки которых запускает долго работающий сервер с помощью другого инструмента, например приложения Fresh, где deno task dev запускает Vite. В таких случаях запустите сервер разработки с включенным инспектором и подключите к нему VS Code.

Сначала добавьте задачу, которая запускает сервер разработки под инспектором Deno. Для приложения Fresh, у которого задача dev — это vite, добавьте вариант для отладки:

{
  "tasks": {
    "dev": "vite",
    "dev:debug": "deno run --inspect -A npm:vite"
  }
}

--inspect запускает инспектор V8 на 127.0.0.1:9229 без приостановки выполнения. Если нужно отладить код, который выполняется при запуске до первого запроса, используйте вместо него --inspect-wait.

Затем добавьте конфигурацию attach в .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to dev server",
      "type": "node",
      "request": "attach",
      "port": 9229
    }
  ]
}

Запустите deno task dev:debug, затем запустите конфигурацию «Attach to dev server» на панели Run and Debug. Точки останова, установленные в коде серверной части (например, в обработчиках маршрутов Fresh), будут срабатывать при следующем соответствующем запросе.

Задачи

Хотя расширение взаимодействует непосредственно с языковым сервером, иногда может быть удобнее запускать команды Deno через CLI. Задачи можно определить в файле deno.json в корне рабочей области, используя поле tasks.

Использование контейнера разработки

Использование контейнера разработки в VS Code — отличный способ создать изолированную среду разработки, не устанавливая Deno CLI в локальной системе. Deno поддерживает контейнеры разработки, и расширение Deno работает с ними.

Если вы хотите добавить поддержку контейнеров разработки в существующий проект Deno, выполните команду Remote-Containers: Add Development Container Configuration Files... в палитре команд, выберите Show All Definitions..., а затем найдите конфигурацию Deno. Будет создана базовая конфигурация .devcontainer, которая установит в контейнер последнюю версию Deno CLI.

После этого VS Code предложит открыть проект в контейнере разработки. Если согласиться, VS Code соберет контейнер разработки и повторно откроет рабочую область в нем. В контейнере будут установлены Deno CLI и расширение vscode_deno.

Устранение неполадок

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

Ошибки и диагностика

An import path cannot end with a '.ts' extension. или Cannot find name 'Deno'.

Обычно это означает, что Deno не включен в проекте Deno. Если посмотреть на источник диагностического сообщения, скорее всего, вы увидите ts(2691). ts указывает, что сообщение поступает от встроенного механизма TypeScript/JavaScript в VS Code. Проверьте, правильно ли задана конфигурация и включен ли параметр Deno: Enable — deno.enable.

Также можно проверить текущую активную конфигурацию, которую видит языковой сервер Deno, выполнив команду Deno: Language Server Status в палитре команд. Откроется документ от языкового сервера с разделом «Workspace Configuration». В нем будет показана конфигурация, переданная языковому серверу VS Code.

Также проверьте, отключена ли настройка VS Code enableProjectDiagnostics, находящаяся в разделе TypeScript › Tsserver › Experimental: Enable Project Diagnostics. Эта настройка позволяет языковому серверу TypeScript работать в фоновом режиме и проверять весь проект целиком. Deno не может отключить это поведение, поэтому ошибки продолжают отображаться, даже если все остальные параметры заданы правильно.

Если там для "enable" задано значение true, а сообщение об ошибке по-прежнему отображается, попробуйте перезапустить VS Code: часть расширения, которая «приглушает» встроенные диагностические сообщения TypeScript для файлов, работает не так, как задумано. Если после перезапуска проблема сохраняется, возможно, вы столкнулись с непредусмотренной ошибкой. В этом случае поищите похожие проблемы и сообщите об ошибке на странице https://github.com/denoland/vscode_deno.