A Dagger module for Deno projects, written in Dang.
It does not just wrap the deno CLI. It models a Deno project as a typed
object graph and maps Deno's toolchain onto Dagger's first-class verbs, so you
get:
- CI by design — the very same checks run at your desk and in CI, in one
pinned, consistent environment.
dagger checklocally is byte-for-byte what CI runs, so there is no separate pipeline to maintain and no "works on my machine". - Reproducible toolchains — a pinned Deno version and base image, the same everywhere.
- Warm dependency cache —
DENO_DIRmounted as a Dagger cache volume, shared across every run. - Reviewable formatting that can't go stale —
deno fmtcomes back as a changeset you preview and confirm before anything is written (great for agents and PR bots). And because Dagger surfaces every@generateas a check as well, a formatting generator doubles as an "is formatting up to date?" check — CI fails when the output drifts, with no extra wiring. - Monorepo-aware — a Deno workspace
(a root
deno.jsonwith aworkspacearray) is a first-class object: checks fan out across every member, and a single member's checks still resolve the shared lockfile, import map, and sibling packages. - Selectable — projects, workspaces and their test files are Dagger
collections, so you can list them and run checks on just the ones you name
(
--deno-project=apps/api,--deno-projects-test-file=apps/api/main_test.ts). Each test file is its own check, and every selected file of a project still runs in onedeno test. - Composability — install Deno into any container, produce standalone binaries, and extend it from your own module.
See designs/deno-module.md for the full design.
Requires Dagger v1.0.0-beta.22 or later (selected collection arguments on checks).
The examples below use this layout: two standalone projects and a Deno workspace with two members.
apps/api/deno.json standalone project
apps/web/deno.json standalone project
packages/deno.json Deno workspace: { "workspace": ["./core", "./ui"] }
packages/core/deno.json member
packages/ui/deno.json member
1. Install the module into your workspace:
dagger install github.com/dagger/denoThis adds a [modules.deno] entry to your dagger.toml. Its settings:
| Setting | Default | Meaning |
|---|---|---|
version |
unset | Deno version for the default base image (denoland/deno:alpine-<version>). Unset, each project uses its .dvmrc, else 2.9.8. See Deno version. |
base |
unset | Base container for Deno commands; it must have deno on PATH. Unset, the image above. |
permissions |
"config" |
Permissions for test and compile: "config" (the deno.json permission sets, -P), "all" (-A) or "none". See Test permissions. |
testArgs |
[] |
Extra deno test flags, e.g. ["--doc", "--parallel", "--ignore=_tools/"]. |
typeCheckArgs |
[] |
Extra deno check flags, e.g. ["--allow-import"]. |
typeCheckTargets |
["."] |
What type-check checks, relative to each project or workspace root, e.g. ["mod.ts"]. See Type-check. |
dagger settings deno lists them (its VALUE column shows only what you've
set). Set one with dagger settings deno <key> <value>; list values are JSON:
dagger settings deno version 2.9.8
dagger settings deno permissions all
dagger settings deno testArgs '["--doc"]'
dagger settings -u deno testArgs # unset: back to the defaultThe first three write
[modules.deno.settings]
version = "2.9.8"
permissions = "all"
testArgs = ["--doc"]The same settings apply to every project and workspace the module checks.
The Deno version is, in order of precedence:
- the
versionsetting, when set; - the nearest
.dvmrcat or above the project (or Deno workspace) root, so a monorepo can keep one at the top and override it per project; - the module's fallback,
2.9.8.
.dvmrc holds a bare version (2.9.8, or v2.9.8); only its first line is
read. dagger settings deno shows no default for version because an unset
setting is what lets .dvmrc apply. dagger settings -u deno version goes
back to .dvmrc. To see what a project resolves to:
dagger call deno toolchain-version --path apps/api2. Run checks and generators. Projects and workspaces are discovered from where you stand (see Discovery):
dagger check # lint, type-check and format-check every project and workspace, and test every test file
dagger generate -y # format: runs `deno fmt` and writes the resultThese are Dagger's first-class verbs, so the same commands run identically in CI
— there is no separate pipeline to maintain. And because Dagger surfaces every
generator as a check too, dagger check also fails when your formatting is out
of date (the stale check).
3. Select what runs by project, workspace, or check name:
dagger list deno-projects -a # standalone projects, by path
dagger list deno-workspaces -a # Deno workspaces, by root path
dagger list deno-test-files -a # test files, by path
dagger check -l --all # one line per project/workspace/test file and check
dagger check --deno-project=apps/api # every check on one project
dagger check --deno --check test --deno-project=apps/api --deno-project=apps/web
dagger check deno/projects/lint # one check on every project
dagger check deno/workspaces/test-files/test --deno-workspace=packages
dagger check --deno-projects-test-file=apps/api/main_test.ts # one test file
dagger generate -y --deno-project=apps/api # format just that project
dagger -W ./apps/api check # or scope by directoryOr just cd into the project: from inside it, it is the only one selected, with
no flag needed:
cd apps/api/src && dagger check # checks apps/api4. Or call functions directly. dagger call reaches the rest of the API:
looking a project up by path, its workspace root, compile, container.
--path may point inside a project; it snaps up to the nearest deno.json /
deno.jsonc (pass --find-up=false when it is already a root):
dagger call deno project --path apps/api/src path # -> apps/api
dagger call deno project --path apps/api testUse
dagger checkin CI.dagger callon a check function (lint,type-check,format-check) prints the result, but the command exits 0 even when the check fails.dagger checkfails the command. A project'stestis a plain function, not a check, sodagger call ... testfails when a test does.
Don't want to install? Run a function one-off with
-m, dropping the module name:dagger -m github.com/dagger/deno call project --path apps/api path.
dagger check, dagger generate and dagger list find Deno configs with
Workspace.findRoots, starting from the directory you run them in:
- every directory with a
deno.json/deno.jsoncat or below it, and - when that directory is not itself a project root, the nearest project enclosing it.
So:
| You run from | Selected |
|---|---|
a project root (apps/api) |
that project, and any project below it |
inside a project (apps/api/src) |
that project (the enclosing one), and any project below |
a directory in no project (the repo root, apps) |
every project below it |
A project above a project root you stand in is not selected; project /
workspace still reach it by path.
Each config directory then lands in exactly one collection:
- A directory whose config declares a non-empty
workspacearray is a Deno workspace (workspaces, keyed by its root). The config is the one deno reads:deno.jsonwhen a directory has both, anddeno.jsoncis parsed as JSONC, so comments and trailing commas are fine. A config that doesn't parse counts as a standalone project, whose checks then fail with deno's error. - A directory below a discovered workspace root is one of its members and is checked through the workspace, not on its own.
- Every other directory is a standalone project (
projects, keyed by its root).
Inside a workspace member (packages/ui/src), the member is the nearest
enclosing project, so the member is selected — not the whole workspace. Its
commands run from the workspace root with the member as the target
(deno test ui), as a workspace's own CI does, so the shared deno.lock,
import map and sibling packages resolve and tests see the root as their cwd;
dagger check there checks just that member.
Inside a workspace directory that belongs to no member (packages/docs), the
workspace itself is selected.
Keys are workspace-root-relative paths. Listing runs no container and no deno:
one findRoots walk, one ripgrep search for configs mentioning "workspace"
(only those few are read and parsed), and a findUp hop per enclosing project
to find the workspace a project belongs to. node_modules is skipped.
Discovery is static, so it doesn't evaluate deno.json beyond the workspace
array: a member listed in a workspace but missing its own config is covered by
the workspace but never selected on its own, and a directory below a workspace
root counts as a member even if the workspace array doesn't list it.
A Deno workspace — a
root deno.json with a workspace array of member packages sharing one
deno.lock and import map — is modeled as a workspace object. Its checks run a
single deno command at the root, so the toolchain fans out across every member:
# run all members' checks at once (deno fans out from the root)
dagger check --deno-workspace=packages
dagger check deno/workspaces/test-files/test --deno-workspace=packages
# list the members
dagger call deno workspace --path packages members pathTo work on one member, run from inside it — the member is then the only
project selected — or use project with the member's path. Its checks run from
the workspace root (so the shared lockfile and sibling @scope/pkg imports
resolve) and pass the member's directory as the target — deno lint ui,
deno test ui, deno check ui, deno fmt --check ui — so they cover that
member only. Its container has the whole workspace mounted with the member as
the workdir, for your own commands:
cd packages/ui && dagger check # just the ui member
dagger call deno project --path packages/ui workspace-root # -> packagesdagger check / dagger generate handle the mix automatically: each discovered
workspace is checked (with deno fanning out) and each standalone project is
checked on its own — members are never run twice. A workspace's members is a
plain list rather than a collection for that reason: its members are checked
through the workspace, not one by one. A workspace's test files are keyed
across all its members and run in one deno test at the root (see
Tests).
| Function | Runs | One check per |
|---|---|---|
lint |
deno lint |
project / workspace |
type-check |
deno check |
project / workspace |
format-check |
deno fmt --check |
project / workspace |
test |
deno test |
test file (see Tests) |
lint, type-check and format-check exist on a project (project …) and on
a workspace (workspace …, running across every member at once). test is a
check on each test file in a project's or workspace's testFiles.
projects and workspaces on the root are collections, which is how
dagger check finds them, and each item's testFiles is a collection too:
| Collection | Keys | Dimension flag | Check addresses |
|---|---|---|---|
projects |
standalone project roots | --deno-project=PATH |
deno/projects/lint, …/type-check, …/format-check |
workspaces |
Deno workspace roots | --deno-workspace=PATH |
deno/workspaces/lint, …/type-check, …/format-check |
a project's testFiles |
test file paths | --deno-projects-test-file=PATH |
deno/projects/test-files/test |
a workspace's testFiles |
test file paths | --deno-workspaces-test-file=PATH |
deno/workspaces/test-files/test |
Test files are reached under two parents, so Dagger gives them one flag per
parent: select a standalone project's file with --deno-projects-test-file
and a workspace member's with --deno-workspaces-test-file. Two different
dimension flags narrow together, so passing both selects nothing.
The generators are deno/projects/format and deno/workspaces/format, and
their staleness checks deno/projects/format/stale and
deno/workspaces/format/stale. dagger check --help lists the flags in effect:
--deno (--by-deno) selects this module, --deno-projects /
--deno-workspaces / --deno-projects-test-files a whole dimension.
The collections' own lint, test, typeCheck, formatCheck and format
are plain functions, not checks or generators, so dagger check never runs the
same work twice. Each runs its command on every selected item in parallel, then
fails naming each item that failed; format returns one changeset over the
selected items. There is no .batch namespace.
Each test file has its own check. Every selected file of one project or
workspace calls the same helper, which runs one deno test and indexes its
report; the engine deduplicates the identical container operations, so N
selected files cost one run per project or workspace. Separate projects and
workspaces run separately, each in its own container with its own config and
lockfile.
- Discovery runs no container: a test file is what
deno testcollects when it walks a directory —test.*,*_test.*or*.test.*with a.ts,.tsx,.mts,.cts,.js,.jsx,.mjsor.cjsextension, hidden directories included,node_modulesleft out — minus the config'sexcludeandtest.exclude, and limited totest.includewhen it is set. In a workspace, each member's own config excludes apply too. A standalone project's files stop at a nested directory with its owndeno.json, which is a project of its own. A file must also register a test itself (Deno.test, orit/test/describeas@std/testing/bddandnode:testdo): an empty placeholder or a file that only imports tests is no check, as go leaves out test files that declare no test. Listing reads the configs, globs the tree and runs one ripgrep search; it never runsdenoor a test, and a config that doesn't parse only drops its patterns. - The command. With every file of a project selected, the run is the
project's own
deno test(with<member>for a workspace member), so deno decides what runs and a failing test file discovery missed still fails the checks. Once the selection leaves a file out (or the project holds a nested project), the selected files are passed explicitly, in byte order. Either way it adds--junit-pathand thepermissionsandtestArgssettings, and its exit code is a result, not an error. - The report. A small indexer reads deno's JUnit report and its stdout once and writes one bounded result per selected file (the last 32 KiB of each output stream, at most 96 KiB per file), so a check's message stays small however large the run.
Attribution:
- A failing test fails the check of the file deno reports it in, with the failure's message and stack; the other files pass.
- A module that throws outside any test fails only its own file's check.
deno teststopping before any test runs — a type error, a module that doesn't load, a bad flag intestArgs— fails every selected file of that project, with deno's error.- A failing test an imported helper registers is reported in the helper's file by JUnit; deno's output says which test module ran it, so it fails only the checks of the selected files that imported it.
- A failure that can't be placed on a selected file — a doc test, a test file discovery doesn't list, a helper's test run by an unselected module — fails every file sharing the run. So does a failing exit with no failure to pin on a file.
- A project whose config deno can't parse fails its own selected files, with deno's error naming the config; other projects are unaffected.
- A selected file deno never ran, while the run passed, fails as "did not
run" rather than passing with nothing behind it (an
--ignoreintestArgs, a config pattern discovery doesn't follow). A file that ran but defines no tests passes, as it does for deno. - With
--fail-fastintestArgs, files that never started after a reported failure are not blamed for it.
Logs and spans belong to the check that started the shared run; the other
checks share its result. Test steps are reported with their test. Which
module ran a test is read from deno's human-readable output (its
running N tests from headers, or with --parallel the ./file => prefix on
each test), since the JUnit report doesn't carry it.
A project's and a workspace's test (dagger call deno project --path apps/api test) and the collections' test remain plain functions that run one whole
deno test; testFiles(ws).test(ws) runs the shared helper over a collection
of files (or a subset) and names each failing file.
test runs deno test --permit-no-files, plus a permission flag chosen by the
permissions setting:
"config"(default) runsdeno test -P, which applies the permission set in the project'sdeno.json(test.permissions, or a top-level set). The same policy then applies locally (deno test -P), in CI and here. Deno'sPermissions in the config file is an experimental featurewarning is silenced here (viaDENO_LOG, unlesstestArgssets a log level). A project without a permission set gets no permissions this way, so its tests that need any fail withNotCapable."all"runsdeno test -A. Use it when your CI grants permissions on the command line (deno test -A,--allow-read …), as denoland/std and oak do. Tests run in a container, so-Areaches the container, not your machine."none"passes no flag, so tests get no permissions at all.
dagger settings deno permissions all # for a repo whose CI runs `deno test -A`Config permission sets landed in Deno 2.5.0. If you set version to an
older release, "config" falls back to -A for tests, since -P doesn't
exist there.
Other deno test flags go in testArgs. Doc tests (the code blocks in JSDoc
comments and markdown) only run with --doc:
dagger settings deno testArgs '["--doc", "--parallel", "--ignore=_tools/"]'Large suites can need a lot of memory in the Dagger engine: a test killed for
running out of memory only reports exit code: 137. denoland/std's cbor
tests needed about 12 GiB. Give the engine more memory, or leave the heavy
tests out with --ignore=… in testArgs.
type-check runs deno check . from the project root; the config's exclude
applies. Add flags with typeCheckArgs — for example when tooling scripts
import remote modules:
dagger settings deno typeCheckArgs '["--allow-import"]'typeCheckTargets replaces the ., and like every setting it applies to every
project and workspace the module checks. Each target is resolved against each
root: a workspace member runs deno check <member>/mod.ts, a Deno workspace
deno check mod.ts at its root, a standalone project deno check mod.ts in
its own directory. So ["mod.ts"] only works where every project and
workspace has a mod.ts — a workspace root without one fails with TS2307.
dagger settings deno typeCheckTargets '["mod.ts", "src/"]'When projects differ, leave typeCheckTargets at . and shape what gets
checked per project instead: list what to skip in each deno.json's exclude,
or pass flags with typeCheckArgs.
format returns a changeset. dagger generate runs it on every selected
project and workspace and summarizes the changed files (apps/api/main.ts +3 -1), not the diff itself; it asks before writing. Without a terminal to ask
on (CI, a coding agent), pass -y to write the changes or --no-apply to only
list them:
dagger generate -y --deno-project=apps/api # write them
dagger generate --no-apply --deno-project=apps/api # just list them
dagger -y call deno project --path apps/api format # one project, via callA changeset applies from the directory you run in, so from inside a project
(apps/api/src) format returns only the changes under that directory; the
stale check there covers the same part. format-check still checks the whole
project.
compile returns the compiled executable as a File — export it or feed it into
an image. The build runs in a Linux container, so cross-compile with --target
if you need a different platform.
dagger call deno project --path apps/api \
compile --entrypoint main.ts export --path ./bin/app
# cross-compile
dagger call deno project --path apps/api \
compile --entrypoint main.ts --target x86_64-unknown-linux-gnu export --path ./bin/appLike test, compile takes its permissions from the permissions setting: with
"all" the binary is built with -A, with "none" with no permissions. With
the default "config", the baked-in permissions come from deno.json: declare
the app's default runtime permissions in a top-level permissions.default set
(this is the deno compile -P set, distinct from test.permissions). Below
Deno 2.5.0, "config" builds with no permissions rather than -A:
// deno.json
{
"permissions": {
"default": { "net": true }
}
}toolchain is a ready-to-use container (Deno + cache) for a path: base if set,
otherwise the alpine image at the resolved version. install
adds the Deno CLI at that version to a container you provide (a glibc base such
as debian/ubuntu/distroless-cc; for musl/alpine use toolchain).
# drop into a shell with deno available
dagger call deno toolchain terminal
# print the Deno version a path resolves to
dagger call deno toolchain-version --path apps/apiThe settings (see Quick start) are also the module's
constructor arguments, so dagger call takes them before the function. For
dagger check, set them with dagger settings instead.
# pin a specific Deno version
dagger call deno --version 2.9.8 toolchain-version
# bring your own base image
dagger call deno --base docker.io/denoland/deno:debian project --path apps/api \
compile --entrypoint main.ts export --path ./bin/app
# grant all permissions and run doc tests (a check: exits 0 even if it fails)
dagger call deno --permissions all --test-args=--doc project --path apps/api testInstall the module as a dependency and call it by name. This is where the real
value is: reuse the toolchain, add your own checks, ship images, and expose the
@up service the base module intentionally leaves to you.
dagger-module.toml:
[[dependencies]]
name = "deno"
source = "github.com/dagger/deno"main.dang:
type MyApp {
"""
CI for this app: reuse Deno's checks, add our own.
"""
ci(ws: Workspace!): Void @check {
let project = deno(version: "2.9.8", permissions: "all", testArgs: ["--doc"])
.project(ws, "apps/api")
run(project.lint(ws))
run(project.typeCheck(ws))
# `test` is a plain function: it raises when a test fails.
project.test(ws)
# Or through the collections: every standalone project, one of them, or
# some of them. Keys are workspace-root-relative project paths. The
# collections' functions are plain helpers too.
let projects = deno.projects(ws)
projects.test(ws)
run(projects.get(key: "apps/web").lint(ws))
projects.subset(keys: ["apps/api", "apps/web"]).formatCheck(ws)
deno.workspaces(ws).typeCheck(ws)
# Some of a project's test files, in one shared `deno test`.
project.testFiles(ws).subset(keys: ["apps/api/main_test.ts"]).test(ws)
null
}
"""
A check called through a dependency comes back as a Check that has not run:
ask whether it passed.
"""
let run(check: Check!): Void {
if (check.pass == false) {
raise check.error.message ?? "check failed"
}
null
}
"""
Ship a minimal image from the compiled binary.
"""
image(ws: Workspace!): Container! {
let bin = deno.project(ws, "apps/api").compile(ws, entrypoint: "main.ts")
container
.from("debian:stable-slim")
.withFile("/app", bin, permissions: 493)
.withEntrypoint(["/app"])
}
"""
Run this app's dev server with `dagger up`.
"""
serve(ws: Workspace!): Service! @up {
deno
.project(ws, "apps/api")
.container(ws)
.withExposedPort(8000)
.asService(args: ["deno", "serve", "--allow-net", "--port", "8000", "main.ts"])
}
}
The collections' helpers (projects(ws).lint(ws), .test, .typeCheck,
.formatCheck, and .format returning a Changeset) take the same ws; so
does each item's function. Calling them from Dang runs them over the
collection as you pass it: only dagger check applies the CLI's selection.
The module is split into deno.dang (root Deno type, the DenoProjects /
DenoWorkspaces / DenoTestFiles collections and DenoTestFile),
deno-project.dang (DenoProject), and deno-workspace.dang
(DenoWorkspace). helpers/deno-test-report is the test report indexer, a
dependency-free Deno script with its own unit tests.
End-to-end tests live in .dagger/modules/e2e: a Dang
module that installs this module and drives it against the sample projects under
.dagger/modules/e2e/modules (a clean project, a badly formatted one, one with a
jsr dependency, and a Deno workspace with two members that import each other).
# run the e2e checks
dagger check -m .dagger/modules/e2e
# or from the workspace root (also runs them)
dagger check
# just the selection checks
dagger check 'e2e:selected-*'Direct Dang calls don't apply the engine's filtered collection view, so the
selected-* checks drive selection through the CLI instead: each writes a
fixture with a dagger.toml that installs this module, and runs the
engine-provided, version-matched dagger check in a session of its own. They
cover several projects and a workspace, excluded files not running, one
command per project (selected-shared-run-check), an isolated failure, a type
error, an uncaught error, a helper's failing test, a failure outside any
selected file (the whole-run path), --parallel, an unparsable config, and a
selected file that never ran. listing-runs-no-tool-check lists every test
file with a testArgs that breaks every run and asserts no deno exec ran.
Run them with Dagger v1.0.0-beta.22 or later.