Workspaces and monorepos

Deno supports workspaces, also known as "monorepos", which allow you to manage multiple related and interdependent packages simultaneously.

A "workspace" is a collection of folders containing deno.json or package.json configuration files. The root deno.json file defines the workspace:

{
  "workspace": ["./add", "./subtract"]
}

This configures a workspace with add and subtract members, which are directories expected to have deno.json(c) and/or package.json files.

Example Jump to heading#

Let's expand on the deno.json workspace example and see its functionality. The file hierarchy looks like this:

/
├── deno.json
├── main.ts
├── add/
│     ├── deno.json
│     └── mod.ts
└── subtract/
      ├── deno.json
      └── mod.ts

There are two workspace members (add and subtract), each with mod.ts files. There is also a root deno.json and a main.ts.

The top-level deno.json configuration file defines the workspace and a top-level import map applied to all members:

{
  "workspace": ["./add", "./subtract"],
  "imports": {
    "chalk": "npm:chalk@5"
  }
}

The root main.ts file uses the chalk bare specifier from the import map and imports the add and subtract functions from the workspace members. Note that it imports them using @scope/add and @scope/subtract, even though these are not proper URLs and aren't in the import map. How are they resolved?

import chalk from "chalk";
import { add } from "@scope/add";
import { subtract } from "@scope/subtract";

console.log("1 + 2 =", chalk.green(add(1, 2)));
console.log("2 - 4 =", chalk.red(subtract(2, 4)));

In the add/ subdirectory, we define a deno.json with a "name" field, which is important for referencing the workspace member. The deno.json file also contains example configurations, like turning off semicolons when using deno fmt.

{
  "name": "@scope/add",
  "version": "0.1.0",
  "exports": "./mod.ts",
  "fmt": {
    "semiColons": false
  }
}

export function add(a: number, b: number): number {
  return a + b;
}

The subtract/ subdirectory is similar but does not have the same deno fmt configuration.

{
  "name": "@scope/subtract",
  "version": "0.3.0",
  "exports": "./mod.ts"
}

import { add } from "@scope/add";

export function subtract(a: number, b: number): number {
  return add(a, b * -1);
}

Let's run it:

> deno run main.ts
1 + 2 = 3
2 - 4 = -2

There's a lot to unpack here, showcasing some of the Deno workspace features:

1. This monorepo consists of two packages, placed in ./add and ./subtract directories.

2. By using name and version options in members' deno.json files, it's possible to refer to them using "bare specifiers" across the whole workspace. In this case, the packages are named @scope/add and @scope/subtract, where scope is the "scope" name you can choose. With these two options, it's not necessary to use long and relative file paths in import statements.

3. npm:chalk@5 package is a shared dependency in the entire workspace. Workspace members "inherit" imports of the workspace root, allowing to easily manage a single version of a dependency across the codebase.

4. add subdirectory specifies in its deno.json that deno fmt should not apply semicolons when formatting the code. This makes for a much smoother transition for existing projects, without a need to change tens or hundreds of files in one go.

Deno workspaces are flexible and can work with Node packages. To make migration for existing Node.js projects easier you can have both Deno-first and Node-first packages in a single workspace.

Migrating from npm workspaces Jump to heading#

Deno workspaces support using a Deno-first package from an existing npm package. In this example, we mix and match a Deno library called @deno/hi, with a Node.js library called @deno/log that we developed a couple years back.

We'll need to include a deno.json configuration file in the root:

{
  "workspace": {
    "members": ["hi"]
  }
}

Alongside our existing package.json workspace:

{
  "workspaces": ["log"]
}

The workspace currently has a log npm package:

{
  "name": "@deno/log",
  "version": "0.5.0",
  "type": "module",
  "main": "index.js"
}

export function log(output) {
  console.log(output);
}

Let's create an @deno/hi Deno-first package that imports @deno/log:

{
  "name": "@deno/hi",
  "version": "0.2.0",
  "exports": "./mod.ts",
  "imports": {
    "log": "npm:@deno/log@^0.5"
  }
}

import { log } from "log";

export function sayHiTo(name: string) {
  log(`Hi, ${name}!`);
}

Now, we can write a main.ts file that imports and calls hi:

import { sayHiTo } from "@deno/hi";

sayHiTo("friend");

$ deno run main.ts
Hi, friend!

You can even have both deno.json and package.json in your existing Node.js package. Additionally, you could remove the package.json in the root and specify the npm package in the deno.json workspace members. That allows you to gradually migrate to Deno, without putting a lot of upfront work.

For example, you can add log/deno.json like to to configure Deno's linter and formatter:

{
  "fmt": {
    "semiColons": false
  },
  "lint": {
    "rules": {
      "exclude": ["no-unused-vars"]
    }
  }
}

Running deno fmt in the workspace, will format the log package to not have any semicolons, and deno lint won't complain if you leave an unused var in one of the source files.

Configuring built-in Deno tools Jump to heading#

Some configuration options only make sense at the root of the workspace, eg. specifying nodeModuleDir option in one of the members is not available and Deno will warn if an option needs to be applied at the workspace root.

Here's a full matrix of various deno.json options available at the workspace root and its members: