Файл конфигурации (deno.json)

На этой странице описаны поля, которые можно задать в файле конфигурации deno.json (или deno.jsonc). Обзор того, как Deno обнаруживает и применяет конфигурацию и как deno.json связано с package.json, см. на странице с описанием концепции Конфигурация.

Зависимости

Поле "imports" в deno.json позволяет указать зависимости, используемые в проекте. С его помощью можно сопоставлять короткие спецификаторы с URL-адресами или путями к файлам, упрощая управление зависимостями и разрешение модулей в приложениях.

Например, если вы хотите использовать в проекте модуль assert из стандартной библиотеки, можно использовать такую карту импорта:

{
  "imports": {
    "@std/assert": "jsr:@std/assert@^1.0.0",
    "chalk": "npm:chalk@5"
  }
}

После этого в скрипте можно использовать короткий спецификатор @std/assert:

import { assertEquals } from "@std/assert";
import chalk from "chalk";

assertEquals(1, 2);
console.log(chalk.yellow("Hello world"));

Также можно использовать поле "dependencies" в package.json:

{
  "dependencies": {
    "express": "^1.0.0"
  }
}

import express from "express";

const app = express();

Обратите внимание, что для этого потребуется запустить deno install.

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

Пользовательские сопоставления путей

Карту импорта в deno.json можно использовать для более общего сопоставления спецификаторов с путями. Можно сопоставить точный спецификатор со сторонним модулем или непосредственно с файлом либо сопоставить часть спецификатора импорта с каталогом.

{
  "imports": {
    // Map to an exact file
    "foo": "./some/long/path/foo.ts",
    // Map to a directory, usage: "bar/file.ts"
    "bar/": "./some/folder/bar/"
  }
}

Использование:

import * as foo from "foo";
import * as bar from "bar/file.ts";

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

Например:

{
  "imports": {
    "@/": "./"
  }
}

import { MyUtil } from "@/util.ts";

В результате спецификаторы импорта, начинающиеся с @/, разрешаются относительно URL-адреса или пути к файлу карты импорта.

Области действия сопоставлений

Поле "scopes" позволяет переопределить сопоставления импорта для модулей, загружаемых из определённого префикса пути, в соответствии со спецификацией карт импорта. Каждый ключ — это область действия (префикс пути), а его значение — карта импорта, применяемая только к модулям, спецификаторы которых входят в эту область. Это полезно, если разным зависимостям нужны разные версии одного пакета.

{
  "imports": {
    "@std/assert": "jsr:@std/assert@^1.0.0"
  },
  "scopes": {
    "./legacy/": {
      "@std/assert": "jsr:@std/assert@^0.224.0"
    }
  }
}

В этом примере модули в ./legacy/ разрешают @std/assert в более старую версию, а в остальной части проекта используется версия из "imports".

Переопределение пакетов

Поле links в deno.json позволяет переопределять зависимости локальными пакетами, хранящимися на диске. Это похоже на npm link.

{
  "links": [
    "../some-package"
  ]
}

Эта возможность помогает решать несколько распространённых задач разработки:

• исправление ошибок в зависимостях
• локальные закрытые библиотеки
• проблемы совместимости

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

Использование package.json для зависимостей

Задайте для preferPackageJson значение true, чтобы команды управления зависимостями изменяли package.json, а не deno.json:

{
  "preferPackageJson": true
}

Если этот параметр включён, команды deno add, deno install <pkg> и deno remove записывают данные в package.json, создавая его, если он не существует. Это эквивалентно передаче --package-json при каждом запуске. Deno также выдаёт предупреждение, если в deno.json по-прежнему присутствуют imports или scopes, поскольку эти зависимости следует перенести в package.json.

Записи также могут содержать шаблоны glob, что удобно для связывания сразу всех пакетов в каталоге. Поддерживаются шаблоны glob для относительных путей и URL-адресов file://, а шаблон с префиксом ! исключает совпадения:

{
  "links": [
    "../packages/*",
    "!../packages/internal-only"
  ]
}

Задачи

Поле tasks в файле deno.json используется для определения пользовательских команд, которые можно выполнять с помощью команды deno task. Оно позволяет настроить команды и разрешения в соответствии с потребностями проекта.

Это поле похоже на поле scripts в файле package.json, поддержка которого также предусмотрена.

{
  "tasks": {
    "start": "deno run --allow-net --watch=static/,routes/,data/ dev.ts",
    "test": "deno test --allow-net",
    "lint": "deno lint"
  }
}

{
  "scripts": {
    "dev": "vite dev",
    "build": "vite build"
  }
}

Чтобы выполнить задачу, используйте команду deno task, указав после неё имя задачи. Например:

deno task start
deno task test
deno task lint
deno task dev
deno task build

Подробнее см. в разделе deno task.

Линтинг

Поле lint в файле deno.json используется для настройки встроенного линтера Deno. С его помощью можно указать, какие файлы включать в проверку или исключать из неё, а также настроить правила линтинга в соответствии с потребностями проекта.

Например:

{
  "lint": {
    "include": ["src/"],
    "exclude": ["src/testdata/", "src/fixtures/**/*.ts"],
    "rules": {
      "tags": ["recommended"],
      "include": ["ban-untagged-todo"],
      "exclude": ["no-unused-vars"]
    }
  }
}

Эта конфигурация:

• запускает линтер только для файлов в каталоге src/;
• не запускает линтер для файлов в каталоге src/testdata/ и файлов TypeScript в каталоге src/fixtures/;
• указывает применять рекомендуемые правила линтинга;
• добавляет правило ban-untagged-todo;
• исключает правило no-unused-vars.

Полный список доступных правил линтинга см. на странице документации Список правил.

Подробнее о линтинге с помощью Deno.

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

Поле fmt в файле deno.json используется для настройки встроенного форматировщика кода Deno. С его помощью можно настроить форматирование кода, обеспечив единообразие в проекте и упростив чтение кода и совместную работу. Ниже перечислены основные параметры конфигурации:

{
  "fmt": {
    "useTabs": true,
    "lineWidth": 80,
    "indentWidth": 4,
    "semiColons": true,
    "singleQuote": true,
    "proseWrap": "preserve",
    "include": ["src/"],
    "exclude": ["src/testdata/", "src/fixtures/**/*.ts"]
  }
}

Эта конфигурация:

• использует для отступов табуляцию вместо пробелов;
• ограничивает длину строк 80 символами;
• задаёт ширину отступа в 4 пробела;
• добавляет точку с запятой в конце инструкций;
• использует одинарные кавычки для строк;
• сохраняет исходную разбивку текста на строки;
• форматирует файлы в каталоге src/;
• исключает файлы из каталога src/testdata/ и файлы TypeScript из каталога src/fixtures/.

Поле fmt принимает следующие параметры. Для каждого указаны значение по умолчанию и допустимые значения:

Параметр json.trailingCommas отдельно управляет завершающими запятыми в файлах JSON и JSONC, независимо от параметра trailingCommas, который применяется к JavaScript и TypeScript. Значение maintain сохраняет завершающие запятые без изменений, а значение jsonc добавляет завершающие запятые в файлы .jsonc и удаляет их из файлов .json.

Подробнее о форматировании кода с помощью Deno.

Файл блокировки

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

{
  "lock": {
    "path": "./deno.lock",
    "frozen": true
  }
}

Эта конфигурация:

• указывает расположение файла блокировки — ./deno.lock (это значение используется по умолчанию, поэтому его можно не указывать);
• указывает Deno завершать работу с ошибкой при изменении любой зависимости.

По умолчанию Deno использует файл блокировки. Отключить его можно с помощью следующей конфигурации:

{
  "lock": false
}

Конфликты слияния

После слияния веток в deno.lock могут остаться маркеры конфликтов Git. Эти маркеры делают файл недопустимым JSON, из-за чего раньше Deno завершал работу с ошибкой Lockfile may be corrupt. Теперь Deno разрешает такие конфликты за вас: следующая команда, которая читает файл блокировки, объединяет конфликтующие записи и перезаписывает файл в чистом виде. Большая часть файла блокировки состоит из записей, идентифицируемых по ключам, которым всегда соответствует одно и то же значение независимо от ветки, в которой они были созданы. Поэтому при слиянии записи объединяются, и вам не нужно вручную редактировать маркеры.

Минимальный возраст зависимостей

Поле minimumDependencyAge не позволяет Deno устанавливать версии пакетов npm или JSR, опубликованные позднее заданного срока. Недавно опубликованные вредоносные версии обычно обнаруживают и удаляют в течение нескольких дней, поэтому небольшая задержка позволяет пресечь большинство атак на цепочку поставок. Рекомендации по выбору периода ожидания см. в разделе управление цепочкой поставок.

{
  // Don't install versions published less than 3 days ago
  "minimumDependencyAge": "P3D"
}

Значение может быть длительностью в формате ISO-8601, например P3D или PT72H, числом минут (120), датой крайнего срока (2025-09-16) или временной меткой RFC3339, либо значением 0 для отключения.

Начиная с Deno 2.9 по умолчанию действует минимальный период в 24 часа, даже если это поле не задано. Укажите явное значение, чтобы увеличить или уменьшить период, либо задайте 0, чтобы отключить его.

Чтобы исключить отдельные пакеты, используйте объектную форму со списком exclude:

{
  "minimumDependencyAge": {
    "age": "P3D",
    "exclude": ["npm:@mycompany/cli", "jsr:@mycompany/lib"]
  }
}

Та же настройка доступна в виде флага командной строки --minimum-dependency-age и параметра min-release-age в файле .npmrc.

Каталог node_modules

По умолчанию Deno использует локальный каталог node_modules, если в каталоге проекта есть файл package.json.

Управлять этим поведением можно с помощью поля nodeModulesDir в файле deno.json.

{
  "nodeModulesDir": "auto"
}

Для этого поля можно задать следующие значения:

Указывать этот параметр необязательно, используются следующие значения по умолчанию:

• "none", если в каталоге проекта нет файла package.json
• "manual", если в каталоге проекта есть файл package.json

При использовании рабочих пространств этот параметр можно задавать только в корне рабочего пространства. Если указать его в любом из участников, будут выданы предупреждения. Параметр "manual" автоматически применяется только в том случае, если в корне рабочего пространства есть файл package.json.

Зависимости JSR в node_modules

Если используется каталог node_modules, задайте для jsrDepsInNodeModules значение true, чтобы устанавливать зависимости jsr: через реестр совместимости JSR с npm — так же, как это делают npm и pnpm. Каждый спецификатор jsr: преобразуется в формат npm (jsr:@david/dax становится npm:@jsr/david__dax, обслуживаемым с https://npm.jsr.io) и устанавливается в node_modules вместе с пакетами npm. По умолчанию этот параметр отключён.

{
  "jsrDepsInNodeModules": true
}

Параметры компилятора TypeScript

Поле compilerOptions в файле deno.json используется для настройки параметров компилятора TypeScript для проекта Deno. Это позволяет настроить компиляцию кода TypeScript в соответствии с требованиями проекта и принятыми в нём стандартами написания кода.

Если вы переносите проект с Node.js, существующие файлы tsconfig.json работают в Deno без изменений. Список поддерживаемых полей и правила приоритета см. в справочнике по совместимости с tsconfig.json.

Полный список поддерживаемых параметров компилятора, настройки библиотек и дополнительные параметры см. в разделе Настройка TypeScript.

Нестабильные возможности

Поле unstable в файле deno.json используется для включения определённых нестабильных возможностей в проекте Deno.

Эти возможности всё ещё находятся в разработке и пока не входят в стабильный API. Перечислив возможности в массиве unstable, вы можете опробовать их и использовать до официального выпуска.

{
  "unstable": ["cron", "kv", "webgpu"]
}

Подробнее.

Включение и исключение

Во многих настройках (например, lint, fmt) есть свойства include и exclude для указания включаемых файлов.

Включение

Будут включены только указанные здесь пути или шаблоны.

{
  "lint": {
    // only format the src/ directory
    "include": ["src/"]
  }
}

Исключение

Указанные здесь пути или шаблоны будут исключены.

{
  "lint": {
    // don't lint the dist/ folder
    "exclude": ["dist/"]
  }
}

Это правило имеет БОЛЕЕ ВЫСОКИЙ приоритет, чем include, и будет иметь преимущество перед include, если путь соответствует обоим параметрам — include и exclude.

Возможно, вам понадобится исключить каталог, но включить вложенный каталог. Начиная с Deno 1.41.2, можно отменить исключение для более конкретного пути, указав отрицательный шаблон glob после более общего шаблона исключения:

{
  "fmt": {
    // don't format the "fixtures" directory,
    // but do format "fixtures/scripts"
    "exclude": [
      "fixtures",
      "!fixtures/scripts"
    ]
  }
}

Исключение верхнего уровня

Если есть каталог, который вы всегда хотите исключать из форматирования, линтинга, проверки типов, анализа в LSP и т. д., укажите его в массиве исключений верхнего уровня:

{
  "exclude": [
    // exclude the dist folder from all sub-commands and the LSP
    "dist/"
  ]
}

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

{
  "fmt": {
    "exclude": [
      // format the dist folder even though it's
      // excluded at the top level
      "!dist"
    ]
  },
  "exclude": [
    "dist/"
  ]
}

Публикация — переопределение .gitignore

При выполнении команды deno publish учитывается параметр .gitignore. Начиная с Deno 1.41.2, можно включить файлы, исключённые в .gitignore, с помощью отрицательного шаблона исключения:

dist/
.env

{
  "publish": {
    "exclude": [
      // include the .gitignored dist folder
      "!dist/"
    ]
  }
}

Также можно явно указать пути, исключённые в git, в параметре "include":

{
  "publish": {
    "include": [
      "dist/",
      "README.md",
      "deno.json"
    ]
  }
}

Экспорты

Поле exports в файле deno.json позволяет определить, какие пути пакета должны быть общедоступны. Это особенно полезно для управления поверхностью API пакета и обеспечения доступа пользователей только к тем частям кода, которые предназначены для использования.

{
  "exports": "./src/mod.ts" // A default entry point
}

Можно также определить несколько точек входа:

{
  "exports": {
    "./module1": "./src/module1.ts",
    "./module2": "./src/module2.ts",
    ".": "./src/mod.ts" // Default entry point
  }
}

Эта конфигурация:

• открывает module1 и module2 как точки входа пакета;
• назначает ./src/mod.ts точкой входа по умолчанию (.).

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

Чтобы использовать экспорты в коде, импортируйте их следующим образом:

import * as module_1 from "@example/my-package/module1";
import * as module_2 from "@example/my-package/module2";

Разрешения

Начиная с Deno 2.5 наборы разрешений можно хранить в файле конфигурации.

Именованные разрешения

Разрешения можно задавать в виде пар «ключ — значение» в наборах разрешений с произвольными именами под ключом "permissions". В каждом наборе:

• ключ — это имя разрешения, которое указывается после --allow- или --deny- в команде CLI (например, read, write, net, env, sys, run, ffi, import);
• значение — это логическое значение (true / false соответствуют разрешению / запрету), массив строк с путями, доменами и т. п. либо объект с парами «ключ — логическое значение» allow, deny и/или ignore.

{
  "permissions": {
    "read-data": {
      "read": "./data"
    },
    "read-and-write": {
      "read": true,
      "write": ["./data"]
    }
  }
}

Наборы разрешений можно использовать, указав флаг --permission-set=<name> или -P=<name>:

$ deno run -P=read-data main.ts

Разрешения по умолчанию

Специальный ключ разрешения "default" позволяет не указывать имя при использовании флага --permission-set/-P:

{
  "permissions": {
    "default": {
      "env": true
    }
  }
}

Затем запустите команду, указав только -P:

$ deno run -P main.ts

Разрешение, запрет и игнорирование

Для более точной настройки разрешений можно использовать объектную форму с ключами allow, deny и ignore. Это особенно полезно, когда требуется более детальный контроль разрешений, чем тот, который обеспечивают простые логические значения или массивы.

Синтаксис объектной формы

Вместо того чтобы задавать разрешение как логическое значение или массив:

{
  "permissions": {
    "default": {
      "read": true, // Simple boolean form
      "write": ["./data"] // Simple array form
    }
  }
}

можно использовать объектную форму:

{
  "permissions": {
    "default": {
      "read": {
        "allow": ["./data", "./config"],
        "deny": ["./data/secrets"],
        "ignore": ["./data/cache"]
      },
      "write": {
        "allow": ["./output"],
        "deny": ["./output/system"]
      }
    }
  }
}

Доступные разрешения

Поведение ключей allow, deny и ignore зависит от типа разрешения:

• read и env: поддерживают allow, deny и ignore
• write, net, run, ffi, sys и import: поддерживают allow и deny (но не ignore)

Поведение

• allow: явно предоставляет доступ к определённым ресурсам. Может иметь значение true (разрешить всё), false (запретить всё) или быть массивом конкретных путей/значений, для которых доступ разрешён.
• deny: явно запрещает доступ к определённым ресурсам (вызывая исключение PermissionDenied), даже если в других обстоятельствах доступ был бы разрешён. Может иметь значение true (запретить всё), false (не запрещать ничего) или быть массивом конкретных путей/значений, для которых доступ запрещён.
• ignore: (только для разрешений read и env) без ошибок игнорирует попытки доступа к определённым ресурсам. Может иметь значение true, false или быть массивом конкретных путей/значений, попытки доступа к которым нужно игнорировать.

Пример

{
  "permissions": {
    "default": {
      // Allow reading from data directory, but deny access to secrets
      // and silently ignore cache files
      "read": {
        "allow": ["./data"],
        "deny": ["./data/secrets"],
        "ignore": ["./data/cache"]
      },
      // Allow all environment variables except API keys
      "env": {
        "allow": true,
        "ignore": ["API_KEY", "SECRET_TOKEN"]
      },
      // Allow all, but deny 'rm', 'sudo'
      "run": {
        "allow": true,
        "deny": ["rm", "sudo"]
      }
    }
  }
}

Разрешения для тестирования, бенчмарков и компиляции

Разрешения можно при необходимости указать в ключах "test", "bench" или "compile".

{
  "test": {
    "permissions": {
      "read": ["./data"]
    }
  }
}

Либо укажите набор разрешений:

{
  "test": {
    "permissions": "read-data"
  },
  "permissions": {
    "read-data": {
      "read": ["./data"]
    }
  }
}

Если этот параметр задан, необходимо запускать deno test с -P или флагом разрешений:

> deno test
error: Test permissions were found in the config file. Did you mean to run with `-P`?
    at file:///Users/david/dev/example/deno.json
> deno test -P
...runs...
> deno test --allow-read
...runs...
> deno test -A
...runs...

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

Обратите внимание: для определения разрешений test и bench тестовые файлы и файлы бенчмарков в рабочем пространстве используют ближайший deno.json. Это позволяет задавать разные разрешения для разных участников рабочего пространства.

Риск для безопасности

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

Если вас устраивает этот риск, эта возможность будет вам полезна.

Конфигурация компиляции

Блок "compile" настраивает deno compile, избавляя от необходимости указывать флаги при каждом запуске. Можно указать дополнительные файлы или каталоги для включения в исполняемый файл, а также пути, которые нужно исключить:

{
  "compile": {
    "include": ["names.csv", "data", "worker.ts"],
    "exclude": ["data/secrets", "**/*.test.ts"]
  }
}

Флаги --include и --exclude в командной строке объединяются с этими списками, а не заменяют их. Блок "compile" также может содержать permissions (см. раздел Разрешения для тестирования, бенчмарков и компиляции).

Пример файла deno.json

{
  "compilerOptions": {
    "allowJs": true,
    "lib": ["deno.window"],
    "strict": true
  },
  "permissions": {
    "default": {
      "read": {
        "allow": ["./src/"],
        "deny": ["./src/secrets/"]
      },
      "env": {
        "allow": true,
        "ignore": ["TEMP_*"]
      }
    }
  },
  "lint": {
    "include": ["src/"],
    "exclude": ["src/testdata/", "src/fixtures/**/*.ts"],
    "rules": {
      "tags": ["recommended"],
      "include": ["ban-untagged-todo"],
      "exclude": ["no-unused-vars"]
    }
  },
  "fmt": {
    "useTabs": true,
    "lineWidth": 80,
    "indentWidth": 4,
    "semiColons": false,
    "singleQuote": true,
    "proseWrap": "preserve",
    "include": ["src/"],
    "exclude": ["src/testdata/", "src/fixtures/**/*.ts"]
  },
  "lock": false,
  "nodeModulesDir": "auto",
  "unstable": ["webgpu"],
  "test": {
    "include": ["src/"],
    "exclude": ["src/testdata/", "src/fixtures/**/*.ts"]
  },
  "tasks": {
    "start": "deno run --allow-read main.ts"
  },
  "imports": {
    "oak": "jsr:@oak/oak"
  },
  "exclude": [
    "dist/"
  ]
}

Это пример файла deno.json, который настраивает параметры компилятора TypeScript, линтер, форматировщик, каталог node_modules и другие компоненты. Полный список доступных полей и параметров конфигурации см. в схеме файла конфигурации Deno.

Схема JSON

Файл схемы JSON доступен для редакторов и обеспечивает автодополнение. Файл имеет версионный номер и доступен по адресу: https://github.com/denoland/deno/blob/main/cli/schemas/config-file.v1.json

Прокси-серверы

Deno поддерживает прокси-серверы для загрузки модулей и API fetch. Настройки прокси считываются из переменных окружения: HTTP_PROXY, HTTPS_PROXY и NO_PROXY.

Если вы используете Windows и переменные окружения не найдены, Deno считывает настройки прокси из реестра.