Поддержка TypeScript

TypeScript — один из основных языков в Deno. Поместите TypeScript в файл и запустите его. Вам не нужно устанавливать компилятор или выполнять сборку, а настройка необязательна: tsconfig.json подойдёт, если он у вас уже есть, но для начала его создавать не нужно.

function greet(name: string): string {
  return `Hello, ${name}!`;
}

console.log(greet("world"));

deno run main.ts

В Deno также встроена проверка типов: deno check выполняет роль tsc --noEmit, причём строгий режим включён по умолчанию. Та же проверка работает в редакторе через языковой сервер Deno, поэтому ошибки типов отображаются по мере ввода.

Как TypeScript выполняется в Deno

Deno рассматривает выполнение TypeScript и проверку типов как две отдельные задачи:

• Выполнение: когда вы deno run файл TypeScript, Deno удаляет типы и передаёт полученный JavaScript в V8. Это выполняется быстро, в том же процессе, а результат кэшируется, но корректность типов при этом не проверяется.
• Проверка типов: deno check (или deno run --check) запускает настоящий компилятор TypeScript для вашего кода, не выполняя его.

Это означает, что ошибки типов не мешают выполнению кода, если вы сами этого не потребуете. Проверка всего графа модулей требует больших ресурсов, поэтому Deno не включает её в цикл редактирования и запуска кода и позволяет запускать её там, где затраты оправданы: в редакторе (через языковой сервер Deno), в CI и в deno test, где проверка типов выполняется по умолчанию.

Важно знать: Deno не записывает JavaScript рядом с исходными файлами. Результат удаления типов помещается во внутренний кэш (его расположение указано как «Кэш скомпилированных модулей» в выводе deno info), поэтому нет ни outDir, ни каталога dist/, ни необходимости настраивать карты исходного кода. При этом трассировки стека ошибок по-прежнему указывают непосредственно на исходные файлы .ts. Если вам действительно нужны файлы .js на диске (например, чтобы распространять библиотеку среди пользователей Node или сборщика), воспользуйтесь отдельным инструментом: deno transpile или deno pack.

Переход с Node.js

Если вы сейчас пишете на TypeScript для Node.js, для большинства инструментов у вас уже есть встроенная замена:

Чаще всего разработчиков Node.js сбивают с толку три различия:

В импортах используются настоящие расширения файлов. В Deno указывается import { greet } from "./greet.ts" — фактическое расширение файла на диске. В tsc вместо этого пришлось бы написать ./greet.js, чтобы импортировать файл с именем greet.ts, или включить параметр allowImportingTsExtensions, который tsc разрешает использовать только вместе с noEmit. Deno не нужны ни один из этих обходных путей, поскольку он ничего не генерирует. Подробнее о разрешении модулей, в том числе пакетов npm, см. в разделе Модули.

Deno поддерживает весь язык TypeScript. Встроенное удаление типов в Node обрабатывает только синтаксис, который можно удалить. Для функций, генерирующих код времени выполнения (перечислений, пространств имён со значениями времени выполнения и свойств параметров), нужен экспериментальный флаг Node --experimental-transform-types, который всё ещё присутствует в Node 24. Deno поддерживает все эти возможности без флагов.

Большинство параметров tsconfig.json настраивают файлы вывода, которые Deno никогда не записывает. Такие параметры, как target, module, outDir, esModuleInterop и sourceMap, влияют на генерируемый JavaScript, который Deno хранит во внутреннем кэше, а не записывает на диск. Deno предупреждает об игнорируемых параметрах, а в таблице миграции в справочнике по конфигурации указано, что делать с каждым из них. В большинстве случаев ответ прост: «удалите параметр».

Если вы переносите весь проект, в руководстве Переход с Node.js описана оставшаяся часть (зависимости, package.json, скрипты npm).

Проверка типов

По умолчанию Deno проверяет типы в строгом режиме. Также включён параметр noImplicitOverride, который tsc оставляет выключенным даже при использовании strict. Все значения по умолчанию перечислены в таблице параметров компилятора.

Проверьте код, не запуская его, с помощью deno check:

# Check the whole project
deno check

# Check a specific file or directory
deno check main.ts
deno check src/

# Also type-check remote modules and npm dependencies
deno check --all main.ts

# Type-check JavaScript files too, without adding @ts-check to each one
deno check --check-js main.js

deno check возвращает ненулевой код завершения при ошибках, поэтому его можно использовать в CI без дополнительной настройки. Показанный выше флаг --check-js описан ниже в разделе Проверка типов в JavaScript. deno check также может проверять блоки кода в комментариях JSDoc и файлах Markdown; см. раздел Тесты документации.

Чтобы проверять типы перед выполнением, добавьте --check в deno run:

deno run --check main.ts

# Include remote modules and npm packages in the check
deno run --check=all main.ts

С этим флагом ошибка типов останавливает процесс до выполнения любого кода. Исправьте ошибку, подавите её с помощью комментария // @ts-expect-error или // @ts-ignore либо уберите флаг.

Проверка типов в deno test и deno bench выполняется по умолчанию. Чтобы пропустить её, передайте --no-check:

deno test --no-check

Более быстрая проверка типов с помощью нативного компилятора (tsgo)

Нативный компилятор TypeScript, написанный на Go и часто работающий примерно в 10 раз быстрее JavaScript-версии tsc, интегрирован в Deno и доступен за нестабильным флагом. В отличие от запуска отдельного исполняемого файла tsgo, интеграция в Deno учитывает разрешение модулей и типы Deno, поэтому спецификаторы jsr: и npm:, а также глобальный объект Deno разрешаются как обычно.

Включите его для одной команды с помощью переменной окружения DENO_UNSTABLE_TSGO или флага --unstable-tsgo:

DENO_UNSTABLE_TSGO=1 deno check main.ts
deno check --unstable-tsgo main.ts

Или включите его для всего проекта в deno.json:

{
  "unstable": ["tsgo"]
}

Настройка параметров компилятора TypeScript

Параметры Deno по умолчанию строгие и современные, поэтому большинству проектов конфигурация не нужна. Если вы хотите изменить поведение средства проверки, задайте параметры в compilerOptions — либо в deno.json, либо в файле tsconfig.json (см. раздел Использование существующего tsconfig.json). Для проектов, изначально созданных для Deno, удобнее хранить их в deno.json, чтобы использовать один файл конфигурации вместо двух:

{
  "compilerOptions": {
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true
  }
}

Полный список поддерживаемых параметров и значений по умолчанию приведён в справочнике по конфигурации. Настройки JSX (React, Preact и других библиотек) описаны в справочнике по JSX.

Использование существующего tsconfig.json

Чтобы попробовать Deno, не нужно преобразовывать конфигурацию. В каждом каталоге рабочей области, содержащем deno.json или package.json, выполняется поиск tsconfig.json; если он найден, Deno автоматически использует его для проверки типов и языкового сервера — флаги не нужны. Начиная с Deno 2.1, jsconfig.json также определяется автоматически при наличии package.json, что удобно для проектов только на JavaScript.

Например, существующий проект Node.js с таким файлом tsconfig.json:

{
  "compilerOptions": {
    "strict": true,
    "jsx": "react-jsx",
    "lib": ["dom", "esnext"],
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["src/**/*"]
}

будет автоматически обнаружен в deno check и языковом сервере Deno. Если позже добавить deno.json с собственным compilerOptions, они будут иметь приоритет. Параметры, связанные с генерацией файлов, игнорируются (с предупреждением), поскольку Deno не записывает выходные файлы.

Для проектов, изначально созданных для Deno, предпочтительнее использовать compilerOptions в deno.json, а не отдельный файл tsconfig.json. Подробные сведения о поддерживаемых полях, правилах приоритета и поведении ссылок на проекты см. в разделе Настройка TypeScript.

Проверка типов в JavaScript

Deno выполняет JavaScript и TypeScript, но по умолчанию проверяет типы только в файлах TypeScript. Есть три способа включить проверку JavaScript-файла: добавить в начало файла директиву // @ts-check, включить compilerOptions.checkJs для всего проекта или передать --check-js в командной строке (deno check --check-js main.js), чтобы разово выполнить проверку без изменения конфигурации.

Когда файл включён в область проверки, средство проверки обнаруживает те же ошибки, что и в TypeScript:

// @ts-check

let x = "hello";
x = 42; // Type 'number' is not assignable to type 'string'.

Директива проверяет один файл; checkJs включает проверку для всего проекта:

{
  "compilerOptions": {
    "checkJs": true
  }
}

В JavaScript-файлах нельзя использовать синтаксис TypeScript, например аннотации типов, но ту же информацию можно указать в комментариях JSDoc, которые средство проверки типов обрабатывает:

// @ts-check

/**
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function add(a, b) {
  return a + b;
}

Предоставление файлов объявлений

При импорте нетипизированного JavaScript-модуля из TypeScript средство проверки считает, что всё, что он экспортирует, имеет тип any. Чтобы исправить это, предоставьте файл объявлений .d.ts (если только в JavaScript уже не добавлены аннотации JSDoc).

Важное отличие от tsc: tsc автоматически обнаруживает файл .d.ts, расположенный рядом с файлом .js с таким же базовым именем. Deno так не делает. Необходимо указать, где находится файл объявлений, — либо в исходном коде JavaScript, либо в месте импорта.

Указание типов в исходном коде

Предпочтительнее объявлять типы непосредственно в файле .js с помощью @ts-self-types, чтобы все импортирующие его модули получали их автоматически:

// @ts-self-types="./add.d.ts"

export function add(a, b) {
  return a + b;
}

export function add(a: number, b: number): number;

Указание типов в импортирующем модуле

Если изменить исходный код JavaScript нельзя, добавьте к импорту аннотацию @ts-types:

// @ts-types="./add.d.ts"
import { add } from "./add.js";

Это также работает для пакетов npm, в которых нет информации о типах: укажите соответствующий пакет @types:

// @ts-types="npm:@types/lodash"
import * as _ from "npm:lodash";

Применение типов ко всем импортам

@ts-types добавляет аннотацию к одному импорту, поэтому для пакета, который используется во всём проекте, повторять её при каждом импорте неудобно. Вместо этого добавьте пакет @types в качестве зависимости. Если типы находятся в локальном каталоге node_modules, Deno автоматически обнаружит их при каждом импорте пакета — так же, как это делает tsc, — без дополнительных аннотаций:

deno add lodash @types/lodash

import { capitalize } from "lodash"; // fully typed, no @ts-types needed

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

{
  "nodeModulesDir": "auto"
}

Без локального каталога node_modules (режим глобального кэша Deno по умолчанию) автоматическое разрешение не применяется; вместо этого используйте показанную выше аннотацию @ts-types для отдельного импорта.

Типизация динамических импортов

Директива @ts-types применяется только к статическим инструкциям import, но не к динамическим import(). Чтобы типизировать динамический импорт модуля без файлов объявлений, используйте утверждение типа, указывающее на соответствующий пакет @types:

const { markedTerminal } = await import(
  "npm:marked-terminal@7"
) as typeof import("npm:@types/marked-terminal@6");

Указание типов для HTTP-модулей

Серверы, на которых размещены JavaScript-модули, могут указывать файл объявлений в заголовке ответа X-TypeScript-Types. Deno разрешает его относительно URL модуля (как заголовок Location) и использует при проверке типов. CDN, например esm.sh, устанавливают этот заголовок за вас.

Поддержка браузеров и веб-воркеров

По умолчанию Deno проверяет код относительно глобальной области выполнения Deno (библиотеки deno.window): доступен Deno.readFile, но недоступен document. Для кода, предназначенного для других сред, можно заменить библиотеки типов с помощью compilerOptions.lib. Типичный пример — код, общий для Deno и браузера:

{
  "compilerOptions": {
    "lib": ["dom", "dom.iterable", "dom.asynciterable", "deno.ns"]
  }
}

Это добавляет глобальные объекты браузера, например document, и при этом сохраняет доступность пространства имён Deno через deno.ns. Для кода, выполняемого в new Worker, используйте lib: ["deno.worker"] (или директиву /// <reference lib="deno.worker" />). В справочнике по свойству lib описаны доступные библиотеки, возможные конфликты и настройки для воркеров.

Расширение глобальных типов

При добавлении полифила для глобального API можно сообщить о нём средству проверки типов с помощью declare global. Обратите внимание: в Deno 2 нет объекта window; глобальные объекты находятся в globalThis, поэтому объявляйте их с помощью var:

declare global {
  var polyfilledAPI: () => string;
}

После импорта этого объявления globalThis.polyfilledAPI проходит проверку типов.

Также можно поместить расширение в файл .d.ts и подключить его директивой тройного слеша (/// <reference types="./global.d.ts" />) или глобально в deno.json:

{
  "compilerOptions": {
    "types": ["./global.d.ts"]
  }
}

Не расширяйте глобальную область, если достаточно обычного импорта: глобальные объявления могут вызывать конфликты имён, затруднять понимание кода и не поддерживаются при публикации в JSR.

Следующие шаги

• Настройте редактор для использования языкового сервера Deno и проверки типов в процессе ввода. См. раздел Настройка среды.
• Ознакомьтесь со справочником по конфигурации TypeScript, где приведена полная таблица параметров компилятора и описана семантика tsconfig.json.
• Проверяйте примеры из документации с помощью тестов документации.
• Переносите существующий проект? Начните с руководства Переход с Node.js.