deno.json

30 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

imports field for dependencies

The "imports" field in deno.json allows you to specify dependencies used in your project. It maps bare specifiers to URLs or file paths, making it easier to manage dependencies and module resolution. Example: {"imports": {"@std/assert": "jsr:@std/assert@^1.0.0", "chalk": "npm:chalk@5"}}. Scripts can then use the bare specifier like import { assertEquals } from "@std/assert".

Custom path mappings in imports

The import map in deno.json supports custom path mappings. Map an exact specifier to a third party module or file directly, or map part of an import specifier to a directory. Example: {"imports": {"foo": "./some/long/path/foo.ts", "bar/": "./some/folder/bar/"}}. Usage: import * as foo from "foo"; import * as bar from "bar/file.ts";

Scoped mappings in imports

The "scopes" field in deno.json lets you override import mappings for modules loaded from a particular path prefix, following the import maps specification. Each key is a scope (a path prefix), and its value is an import map that applies only to modules whose specifier falls under that scope. This is useful when two dependencies need different versions of the same package. Example: {"scopes": {"./legacy/": {"@std/assert": "jsr:@std/assert@^0.224.0"}}}

links field for local package overrides

The "links" field in deno.json allows you to override dependencies with local packages stored on disk, similar to npm link. Example: {"links": ["../some-package"]}. Entries can also be globs like {"links": ["../packages/*", "!../packages/internal-only"]}. The package being referenced doesn't need to be published; it just needs proper package name and metadata in deno.json or package.json.

preferPackageJson field

Set "preferPackageJson" to true in deno.json to make dependency commands target package.json instead of deno.json. With this enabled, deno add, deno install <pkg>, and deno remove write to package.json, creating one if it does not exist. This is equivalent to passing --package-json on every invocation. Deno also warns when "imports" or "scopes" are still present in deno.json.

tasks field for custom commands

The "tasks" field in deno.json is used to define custom commands that can be executed with the deno task command. It is similar to the "scripts" field in package.json. Example: {"tasks": {"start": "deno run --allow-net --watch=static/,routes/,data/ dev.ts", "test": "deno test --allow-net", "lint": "deno lint"}}. Execute tasks with: deno task start, deno task test, deno task lint.

lint field configuration options

The "lint" field in deno.json configures the built-in linter. It supports include, exclude, and rules properties. Example: {"lint": {"include": ["src/"], "exclude": ["src/testdata/", "src/fixtures/**/*.ts"], "rules": {"tags": ["recommended"], "include": ["ban-untagged-todo"], "exclude": ["no-unused-vars"]}}}. The exclude property has higher precedence than include.

fmt field formatting options table

The "fmt" field in deno.json configures code formatter options. Complete table of options with defaults: bracePosition (default: sameLine, values: maintain/sameLine/nextLine/sameLineUnlessHanging), indentWidth (default: 2, number), lineWidth (default: 80, number), newLineKind (default: lf, values: auto/crlf/lf/system), nextControlFlowPosition (default: sameLine, values: sameLine/nextLine/maintain), operatorPosition (default: sameLine, values: sameLine/nextLine/maintain), proseWrap (default: always, values: always/never/preserve), quoteProps (default: asNeeded, values: asNeeded/consistent/preserve), semiColons (default: true, values: true/false), singleBodyPosition (default: sameLineUnlessHanging, values: sameLine/nextLine/maintain/sameLineUnlessHanging), singleQuote (default: false, values: true/false), sortNamedExports (default: caseInsensitive, values: caseInsensitive/caseSensitive/maintain), sortNamedImports (default: caseInsensitive, values: caseInsensitive/caseSensitive/maintain), spaceAround (default: false, values: true/false), spaceSurroundingProperties (default: true, values: true/false), trailingCommas (default: always, values: always/never), typeLiteral.separatorKind (default: semiColon, values: comma/semiColon), useBraces (default: whenNotSingleLine, values: maintain/whenNotSingleLine/always/preferNone), useTabs (default: false, values: true/false), json.trailingCommas (default: never, values: never/always/maintain/jsonc), jsx.bracketPosition (default: nextLine, values: maintain/sameLine/nextLine), jsx.forceNewLinesSurroundingContent (default: false, values: true/false), jsx.multiLineParens (default: prefer, values: never/prefer/always), unstable-component (default: false, values: true/false), unstable-sql (default: false, values: true/false).

json.trailingCommas controls JSON separately from JavaScript

The json.trailingCommas option in fmt controls trailing commas in JSON and JSONC files separately from the trailingCommas option, which applies to JavaScript and TypeScript. The maintain value keeps trailing commas as written, and the jsonc value adds trailing commas in .jsonc files while omitting them in .json files.

lock field configuration

The "lock" field in deno.json specifies configuration of the lock file that Deno uses to ensure integrity of dependencies. Example: {"lock": {"path": "./deno.lock", "frozen": true}}. The path option specifies lockfile location (default: ./deno.lock). The frozen option tells Deno to error out if any dependency changes. Deno uses lockfile by default; disable with {"lock": false}.

Lockfile merge conflict resolution

After merging branches, deno.lock can be left with git conflict markers. Deno now resolves these conflicts automatically: the next command that reads the lockfile merges the conflicting entries and rewrites a clean file. Most of the lockfile is a set of identity-keyed entries where a key always maps to the same value regardless of which branch wrote it, so the merge is a union and you do not need to edit the markers by hand.

minimumDependencyAge field

The "minimumDependencyAge" field stops Deno from installing npm or JSR package versions that were published more recently than the configured age. This catches supply-chain attacks early. The value accepts an ISO-8601 duration such as P3D or PT72H, a number of minutes (120), an absolute cutoff date (2025-09-16) or RFC3339 timestamp, or 0 to disable. Example: {"minimumDependencyAge": "P3D"}. Since Deno 2.9, a 24-hour minimum applies by default. To exempt specific packages, use the object form: {"minimumDependencyAge": {"age": "P3D", "exclude": ["npm:@mycompany/cli", "jsr:@mycompany/lib"]}}.

nodeModulesDir field configuration

The "nodeModulesDir" field controls whether Deno uses a local node_modules directory. Possible values: "none" (don't use local node_modules, use global cache in $DENO_DIR), "auto" (use local node_modules, automatically created and kept up to date), "manual" (use local node_modules, user must keep it up to date). Defaults: "none" if no package.json file, "manual" if package.json file exists. When using workspaces, this setting can only be used in the workspace root.

jsrDepsInNodeModules field

The "jsrDepsInNodeModules" field in deno.json, when set to true, installs jsr: dependencies through JSR's npm compatibility registry. Each jsr: specifier is rewritten to its npm form (jsr:@david/dax becomes npm:@jsr/david__dax, served from https://npm.jsr.io) and installed into node_modules alongside npm packages. The option is off by default. Example: {"jsrDepsInNodeModules": true}.

compilerOptions field for TypeScript settings

The "compilerOptions" field in deno.json is used to configure TypeScript compiler settings for the Deno project. This allows customization of how TypeScript code is compiled. Deno recommends using the default TypeScript configuration to help when sharing code. If migrating from Node.js, existing tsconfig.json files work out of the box with Deno.

unstable field for experimental features

The "unstable" field in deno.json is used to enable specific unstable features for the Deno project. These features are still in development and not yet part of the stable API. Example: {"unstable": ["cron", "kv", "webgpu"]}. By listing features in the unstable array, you can experiment with and use new capabilities before they are officially released.

include property for file filtering

The "include" property in deno.json configurations (like lint, fmt) specifies which paths or patterns to include. Only the paths or patterns specified here will be included. Example: {"lint": {"include": ["src/"]}}. The exclude property has higher precedence than include and will win over include if a path is matched in both.

exclude property for file filtering

The "exclude" property in deno.json configurations specifies paths or patterns to exclude. This has higher precedence than include and will win over include if a path is matched in both. Example: {"lint": {"exclude": ["dist/"]}}. In Deno 1.41.2+, you can un-exclude a more specific path by specifying a negated glob below the more general exclude: {"fmt": {"exclude": ["fixtures", "!fixtures/scripts"]}}.

Top level exclude in deno.json

If there's a directory you never want Deno to fmt, lint, type check, analyze in the LSP, etc., specify it in the top level exclude array. Example: {"exclude": ["dist/"]}. In Deno 1.41.2+, you may un-exclude a path by specifying a negated glob in a more specific config: {"fmt": {"exclude": ["!dist"]}, "exclude": ["dist/"]}.

publish exclude with gitignore override

The .gitignore is taken into account for the deno publish command. In Deno 1.41.2+, you can opt-out of excluded files ignored in .gitignore by using a negated exclude glob: {"publish": {"exclude": ["!dist/"]}}. Alternatively, explicitly specifying gitignored paths in an "include" works as well: {"publish": {"include": ["dist/", "README.md", "deno.json"]}}.

exports field for public API surface

The "exports" field in deno.json allows you to define which paths of your package should be publicly accessible. Can be a single string for a default entry point: {"exports": "./src/mod.ts"}. Can also define multiple entry points: {"exports": {"./module1": "./src/module1.ts", "./module2": "./src/module2.ts", ".": "./src/mod.ts"}}. Users can import these modules using the specified paths, while other files remain private.

permissions field for named permission sets

Deno 2.5+ supports storing permission sets in deno.json under the "permissions" key. Permissions are defined as key-value pairs under arbitrarily-named permission sets. The key is the name of a permission that would follow --allow- or --deny- in the CLI (read, write, net, env, sys, run, ffi, import). The value is a boolean (true/false for allow/deny), an array of strings (paths, domains, etc.), or an object with allow, deny, and/or ignore keys. Example: {"permissions": {"read-data": {"read": "./data"}, "read-and-write": {"read": true, "write": ["./data"]}}}.

Using named permission sets with --permission-set flag

Permission sets defined in deno.json can be used by specifying the --permission-set=<name> or -P=<name> flag. Example: $ deno run -P=read-data main.ts. A special "default" permission key allows excluding the name when using the --permission-set/-P flag: {"permissions": {"default": {"env": true}}}. Then run with just $ deno run -P main.ts.

Permission object form with allow, deny, and ignore

Permissions in deno.json can use the object form for finer control: {"permissions": {"default": {"read": {"allow": ["./data", "./config"], "deny": ["./data/secrets"], "ignore": ["./data/cache"]}, "write": {"allow": ["./output"], "deny": ["./output/system"]}}}. Available permissions: read and env support allow, deny, and ignore; write, net, run, ffi, sys, and import support allow and deny (not ignore).

Permission values: allow behavior

The "allow" key in permission objects explicitly grants access to specific resources. Can be true (to allow all), false (to allow none), or an array of specific paths/values to allow.

Permission values: deny behavior

The "deny" key in permission objects explicitly denies access (throws PermissionDenied error) to specific resources, even if they would otherwise be allowed. Can be true (to deny all), false (to deny none), or an array of specific paths/values to deny.

Permission values: ignore behavior

The "ignore" key (only for read and env permissions) silently ignores access attempts to specific resources without throwing errors. Can be true, false, or an array of specific paths/values to ignore.

test and bench permissions in deno.json

Permissions can be optionally specified within the "test" or "bench" keys in deno.json. Example: {"test": {"permissions": {"read": ["./data"]}}}. Or reference a permission set: {"test": {"permissions": "read-data"}, "permissions": {"read-data": {"read": ["./data"]}}}. When defined, you must run deno test with -P or a permission flag. Note: test and bench files in a workspace use the closest deno.json for determining test and bench permissions.

compile config block for deno compile

The "compile" block in deno.json configures deno compile without requiring flags on every invocation. Can declare which extra files or directories to bundle into the executable, and which paths to exclude. Example: {"compile": {"include": ["names.csv", "data", "worker.ts"], "exclude": ["data/secrets", "**/*.test.ts"]}}. --include and --exclude flags on the command line are merged with these lists rather than replacing them. The compile block can also carry permissions.

Proxies configuration for Deno

Deno supports proxies for module downloads and the fetch API. Proxy configuration is read from environment variables: HTTP_PROXY, HTTPS_PROXY, and NO_PROXY. On Windows, if environment variables are not found, Deno falls back to reading proxies from the registry.

Give your agent this brain