Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 37 ยท Testing and Tooling

Configuration and Tasks with deno.json

Configure a Deno project with deno.json. Define tasks and task dependencies, import maps, compiler options, lockfiles, env files and workspaces, and understand how each setting is resolved.

A Deno script needs no configuration, but a real project soon wants shared settings: a short name for a long command, a friendly name for a dependency, formatter options, a pinned set of dependency hashes. All of it lives in one optional file at the project root: deno.json (or deno.jsonc, which allows comments).

This lesson tours the file field by field and explains how Deno uses it. You will write tasks (Deno's replacement for npm run), import maps, and a workspace for a monorepo.

Deno itself is not available here, so deno commands and config files are read-only. The two runnable examples rebuild the logic of task dependency resolution and import-map lookup in Node so you can see how Deno decides what to run and what a bare name means.

Create a project

Terminal
deno init my-app          # main.ts, main_test.ts, deno.json
cd my-app
deno task dev

The generated deno.json is small:

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

Deno finds the config by looking in the current directory and then in each parent folder, so you can run commands from any subfolder of the project.

Tasks

A task is a named shell command. Tasks run in Deno's own cross-platform shell, so the same task works on Windows, macOS and Linux, and you get &&, ||, ;, pipes, environment variables and a few built-ins such as cp, mv, rm, mkdir, echo, sleep and xargs.

JSON
{
  "tasks": {
    "start": "deno run --allow-net --allow-env=PORT main.ts",
    "dev": "deno run --watch --allow-net --allow-env=PORT main.ts",
    "test": "deno test --allow-net",
    "check": "deno fmt --check && deno lint && deno check main.ts",
    "clean": "rm -rf dist coverage"
  }
}
Terminal
deno task            # list all tasks
deno task dev        # run one
deno task test --filter "slugify"   # extra arguments are appended

A task can also be an object with a description and dependencies, so common sequences are named once:

JSON
{
  "tasks": {
    "fmt": "deno fmt --check",
    "lint": "deno lint",
    "types": "deno check main.ts",
    "test": "deno test",
    "ci": {
      "description": "Everything CI runs",
      "dependencies": ["fmt", "lint", "types", "test"]
    },
    "build": {
      "command": "deno compile --output dist/app main.ts",
      "dependencies": ["ci"]
    }
  }
}

Running deno task build first runs ci (and therefore its four dependencies, in parallel where possible), and only starts build when they all succeed. The stand-in below resolves dependencies the same way: depth first, each task once, in an order that respects the graph.

Node.js Resolving task dependencies

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.

Real Deno also runs independent dependencies concurrently and detects circular dependencies exactly like this.

Imports and the import map

The imports field maps bare specifiers (names with no path) to real URLs, like the browser's import maps:

JSON
{
  "imports": {
    "@std/assert": "jsr:@std/assert@^1.0.0",
    "@std/path": "jsr:@std/path@^1.0.0",
    "hono": "jsr:@hono/hono@^4",
    "zod": "npm:zod@^3.23",
    "@/": "./src/"
  }
}
TypeScript
import { assertEquals } from "@std/assert";   // jsr:@std/assert@^1.0.0
import { z } from "zod";                       // npm:zod@^3.23
import { db } from "@/db.ts";                  // ./src/db.ts (trailing slash = prefix)

You rarely edit this by hand. These commands do it for you and pick the latest compatible version:

Terminal
deno add jsr:@std/assert      # adds the mapping to deno.json
deno add npm:zod
deno remove zod
deno outdated                 # which dependencies have newer versions
deno outdated --update        # update them (use --latest to cross major versions)

Why use an import map at all? One place to see and upgrade versions, shorter imports, and files that do not repeat version numbers. A bare name that is not in the map is an error with a helpful hint. This stand-in shows the lookup rules (exact match first, then the longest matching prefix that ends in /).

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.

Other fields you will meet

JSON
{
  "name": "@me/my-lib",
  "version": "1.2.0",
  "exports": "./mod.ts",
  "compilerOptions": { "strict": true, "jsx": "react-jsx", "jsxImportSource": "preact" },
  "fmt": { "lineWidth": 100 },
  "lint": { "rules": { "tags": ["recommended"] } },
  "test": { "include": ["tests/"] },
  "exclude": ["dist/", "node_modules/"],
  "lock": true,
  "nodeModulesDir": "auto",
  "unstable": ["kv", "cron"]
}
  • name, version, exports are for publishing to JSR.
  • compilerOptions configure TypeScript and JSX.
  • fmt, lint, test, bench hold per-tool options and file lists (see formatting and linting).
  • exclude removes paths from every tool at once.
  • nodeModulesDir controls whether npm packages are placed in a node_modules folder (needed by some tools and bundlers; see npm and Node compatibility).
  • unstable turns on unstable API groups by name, instead of long command-line flags. Which APIs are still unstable changes between releases, so check the release notes.

The lockfile

Deno writes deno.lock automatically. It records the exact resolved version and an integrity hash for every dependency. On later runs Deno verifies downloads against the hashes, so a compromised or changed package fails loudly instead of silently running. Commit deno.lock. To freeze it in CI use deno install --frozen, which errors if the lock would change.

Environment files

Config values and secrets belong in environment variables, not in code:

Terminal
deno run --env-file=.env --allow-env=PORT,DATABASE_URL main.ts
TypeScript
const port = Number(Deno.env.get("PORT") ?? "8000");
const dbUrl = Deno.env.get("DATABASE_URL");
if (!dbUrl) throw new Error("DATABASE_URL is required");

--env-file loads KEY=value lines. Never commit real secrets; commit an .env.example instead.

Workspaces

A workspace groups several packages that live in one repository and depend on each other:

TEXT
my-repo/
  deno.json              <- root
  api/
    deno.json            <- { "name": "@me/api", "version": "0.1.0", "exports": "./mod.ts" }
    mod.ts
  shared/
    deno.json            <- { "name": "@me/shared", "version": "0.1.0", "exports": "./mod.ts" }
    mod.ts
JSON
{
  "workspace": ["./api", "./shared"],
  "tasks": { "test": "deno test" }
}

Inside api/mod.ts you can now write import { slugify } from "@me/shared"; and Deno resolves it to the local folder. Settings in the root file (such as imports, fmt and lint) apply to every member unless a member overrides them. This is the Deno way to build a monorepo without extra tooling.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

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

    It is an import map: names on the left, module specifiers (jsr:, npm:, URLs, paths) on the right.
  2. 2. In the task graph build -> ci -> [fmt, lint, types, test], what happens when lint fails?

    A task starts only after all of its dependencies succeed, so a failing dependency stops the chain.
  3. 3. Why should deno.lock be committed to version control?

    The lockfile makes builds reproducible and detects tampered downloads.
  4. 4. Which flag loads variables from a .env file?

    deno run --env-file=.env loads the file into the environment; you still need --allow-env to read the variables.

Summary

  • deno.json (or .jsonc) is optional config found by searching upward from the current folder.
  • tasks replace npm scripts, run in a cross-platform shell and can list dependencies.
  • imports is an import map; manage it with deno add, deno remove and deno outdated.
  • deno.lock pins versions and hashes; commit it and use --frozen in CI.
  • Use --env-file for configuration, and workspace to share code between packages in one repo.

Next: Deno KV Basics