Config files

Deno reads two configuration files: Node's package.json and its own deno.json. Both are first-class and both are optional, so Deno works with either one or both together. The rule of thumb:

• Use a package.json for dependencies and scripts. Deno reads it directly, so most Node.js projects run with no changes and you do not need a deno.json at all.
• Add a deno.json when you want to configure Deno's own tooling, such as the formatter, linter, TypeScript compiler, or tasks.

package.json Jump to heading#

Deno has first-class package.json support. Point Deno at an existing Node.js project and it resolves the same npm dependencies from package.json and runs the project's scripts with deno task, with no deno.json and no conversion step:

deno install        # install the dependencies from package.json
deno task <script>  # run a script defined in package.json

A package.json configures your project's dependencies and scripts, but it does not configure Deno itself. Deno-specific settings such as the formatter, linter, TypeScript compiler options, and lockfile behavior live only in deno.json. When both files are present, Deno reads dependencies from each and takes its own configuration from deno.json.

This is what lets you adopt Deno incrementally: keep running an app on Node while using Deno as a faster drop-in package manager, run your existing scripts with deno task, and add a deno.json for Deno's toolchain when you are ready. The Migrate from Node.js guide walks through each step, and Node compatibility in Deno covers how the runtime maps Node's APIs and module resolution.

deno.json Jump to heading#

deno.json is where you configure Deno itself: tasks, dependencies, and tools like the TypeScript compiler, linter, and formatter. It is optional; a minimal file looks like this:

{
  "tasks": {
    "dev": "deno run --watch main.ts"
  },
  "imports": {
    "@std/assert": "jsr:@std/assert@^1"
  },
  "fmt": {
    "lineWidth": 100
  }
}

It supports .json and .jsonc extensions, so with deno.jsonc you can add comments and trailing commas.

Deno automatically detects a deno.json or deno.jsonc file in your current working directory or any parent directory, which is what makes a project's settings apply to every file under it. Use the --config flag to point at a different file. In a monorepo, a root deno.json can define a workspace whose members each carry their own deno.json.

What you can configure Jump to heading#

A deno.json file configures Deno's tooling and your project. Every field is documented in the Configuration file (deno.json) reference, including:

• Dependencies and import maps
• Tasks
• Linting and formatting
• Lockfile and the node_modules directory
• TypeScript compiler options
• Unstable feature flags
• include and exclude
• Exports
• Permissions
• Compile options
• Minimum dependency age

See the reference for a full example deno.json file and the JSON schema for editor autocompletion.