Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 37 ยท Modules and Permissions

Import Maps and deno.json

Configure a Deno project with deno.json - import maps for short names, tasks, compilerOptions, fmt and lint settings, exclude, lock files and workspaces for monorepos.

Long import URLs repeated in twenty files are a pain to read and to upgrade. Deno solves it with an import map: a table that maps short names to real locations, so your code can write import { assertEquals } from "@std/assert" and the project file decides which version that means. The map lives in deno.json, the single configuration file for a Deno project. In this lesson you learn what goes in that file and how the pieces fit.

The deno.json file

Deno looks for deno.json (or deno.jsonc, which allows comments) in the current folder and walks up through parent folders until it finds one. It is optional: a one-file script needs none. A typical project file looks like this:

JSON
{
  "name": "@me/my-app",
  "version": "0.1.0",
  "imports": {
    "@std/assert": "jsr:@std/assert@^1.0.0",
    "@std/path": "jsr:@std/path@^1.0.0",
    "express": "npm:express@^4.21.0",
    "@/": "./src/"
  },
  "tasks": {
    "dev": "deno run --watch --allow-net src/main.ts",
    "test": "deno test --allow-read"
  },
  "compilerOptions": { "strict": true },
  "fmt": { "lineWidth": 100, "singleQuote": true },
  "lint": { "rules": { "exclude": ["no-explicit-any"] } },
  "exclude": ["dist/", "coverage/"]
}

Imports

The imports field is an import map. Keys are what code writes; values are where Deno looks:

JSON
{
  "imports": {
    "@std/assert": "jsr:@std/assert@^1.0.0",
    "lodash": "npm:lodash@^4.17.21",
    "lib/": "./src/lib/",
    "chart": "https://esm.sh/chart.js@4"
  }
}

With that map, your code is short and has no versions in it:

TypeScript
import { assertEquals } from "@std/assert";
import _ from "lodash";
import { helper } from "lib/helper.ts"; // trailing slash maps a whole folder

Two rules are worth remembering. A key that ends in / maps every specifier that starts with it, so lib/helper.ts becomes ./src/lib/helper.ts. And the version range (^1.0.0) lives in one place: upgrading a dependency means changing a single line.

You rarely write these lines by hand. deno add edits the file for you:

Terminal
deno add jsr:@std/assert        # adds "@std/assert": "jsr:@std/assert@^1.x"
deno add npm:chalk
deno remove @std/assert

This lookup works like a table, and you can see the idea in a few lines of code. The resolver below applies the same two rules (exact key, then folder prefix).

Node.js How an import map resolves names

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Scopes

An import map can also contain scopes, which override a mapping for modules inside a certain folder, for example to use a different version of a library for one subtree. Most projects never need them. Do not confuse them with permission scopes.

Tasks

The tasks field names commands. A task can be a string, or an object with a description and dependencies:

JSON
{
  "tasks": {
    "build": {
      "description": "Bundle for production",
      "command": "deno run -A scripts/build.ts"
    },
    "ci": {
      "dependencies": ["fmt:check", "lint", "test"]
    },
    "fmt:check": "deno fmt --check",
    "lint": "deno lint",
    "test": "deno test"
  }
}

Dependencies run first (in parallel where possible), so deno task ci runs the three checks. Inside a task you can use &&, ||, |, $ENV_VAR and $(cmd). Extra words you type after the task name are appended: deno task test --filter parse.

Compiler, formatter and linter settings

  • compilerOptions: the TypeScript options you may tweak (TypeScript in Deno).
  • fmt: lineWidth, indentWidth, useTabs, singleQuote, semiColons, proseWrap, and include/exclude.
  • lint: choose rule sets, include or exclude rules and files.
  • test and bench: include and exclude lists.
  • exclude: files that every tool should ignore.

Settings are shared by the CLI and the editor, so what the language server shows matches what CI enforces.

JSON
{
  "fmt": {
    "useTabs": false,
    "lineWidth": 90,
    "exclude": ["generated/"]
  },
  "lint": {
    "rules": {
      "tags": ["recommended"],
      "include": ["no-console"],
      "exclude": ["no-explicit-any"]
    }
  }
}

deno.jsonc and comments

deno.json is strict JSON. If you want comments, name the file deno.jsonc. This small helper shows how a tool might read it, by stripping comments and trailing commas before JSON.parse:

Node.js Reading a commented config file

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

(This regex approach is fine for a demo. Real parsers also respect // inside strings; Deno does this for you.)

Workspaces

A workspace keeps several packages in one repository and gives them a shared deno.json. The root file lists the members:

JSON
{
  "workspace": ["./api", "./shared", "./web"],
  "imports": {
    "@std/assert": "jsr:@std/assert@^1.0.0"
  }
}

Each member has its own deno.json with a name and exports, so the others can import it by name:

JSON
{
  "name": "@acme/shared",
  "version": "1.0.0",
  "exports": "./mod.ts"
}
TypeScript
import { formatPrice } from "@acme/shared"; // resolved inside the workspace

Run one member's task with deno task --filter "api" dev, or all with deno task --recursive test. Workspaces are how you split a large codebase without publishing every part.

flowchart TD
  R["deno.json (workspace root)"] --> A["api/deno.json"]
  R --> S["shared/deno.json"]
  R --> W["web/deno.json"]
  A -->|"imports @acme/shared"| S
  W -->|"imports @acme/shared"| S

Members share root settings and import each other by package name.

Interplay with package.json

Deno 2 also reads package.json. If a project has both, dependencies in package.json are available as bare names, and deno.json can still hold tasks and tool settings. Use one source of truth for dependencies if you can, to keep upgrades simple. The next lesson covers npm packages in detail: JSR and npm Packages.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does the imports field in deno.json do?

    It is an import map: a lookup from the names your code uses to jsr:, npm:, URL or local locations.
  2. 2. A key ending in a slash, such as "lib/", maps which specifiers?

    A trailing slash makes it a prefix mapping for a whole folder.
  3. 3. Which command adds a dependency to deno.json?

    deno add writes the entry in imports with a version range.
  4. 4. How do you allow comments in the config file?

    deno.jsonc is JSON with comments; plain deno.json is strict JSON.
  5. 5. What is a workspace used for?

    A workspace groups member packages under a root deno.json so they can import each other.

Summary

  • deno.json (or deno.jsonc) is the optional project configuration file.
  • imports is an import map; trailing-slash keys map folders; deno add edits it.
  • tasks can be strings or objects with dependencies.
  • compilerOptions, fmt, lint, test and exclude configure the tools.
  • Commit deno.lock with the config for repeatable installs.
  • workspace organises monorepos, with members importing each other by name.

Next: JSR and npm Packages