Agent Skills: Deno Knowledge Patch

Deno Knowledge Patch

Use this skill when choosing Deno APIs, CLI flags, configuration, dependency behavior, or compatibility surfaces. Read the relevant topic reference before changing a project because several commands, APIs, stability gates, and defaults changed during Deno 2.

Working approach

1. Inspect deno --version, deno.json or deno.jsonc, package.json, deno.lock, workspace configuration, and CI commands.
2. Open every reference relevant to the requested change; later version-attributed guidance supersedes earlier behavior only where it explicitly says so.
3. Preserve the project's chosen manifest and node-modules layout. Keep manifest and lockfile changes together.
4. Keep permissions narrow. Do not add -A merely to silence a failure.
5. Verify with the smallest applicable commands: deno check, deno lint, deno fmt --check, deno test, and the requested build, package, or deploy command.

Reference index

| Reference | Topics | | --- | --- | | Build, publish, and deploy | deno compile, bundling, transpilation, tarballs, publication, and deployment | | Dependencies and workspaces | Manifests, registries, npm/JSR resolution, lockfiles, installs, updates, catalogs, and workspaces | | Desktop and ecosystem | Desktop applications, Jupyter, Fresh, Deploy, Sandbox, JSR consumers, and platform releases | | Deno 2 migration | Removed APIs, configuration validation, changed defaults, and runtime baselines | | Networking, servers, and observability | HTTP, sockets, TLS, WebSockets, QUIC, OpenTelemetry, inspectors, and profiling | | Node compatibility | CommonJS, globals, timers, Node modules, filesystem, workers, networking, SQLite, tests, and diagnostics | | Permissions and dependency security | Permission sets, precedence, tracing, brokers, audits, lifecycle trust, and dependency hardening | | Runtime and Web APIs | Filesystem, WebAssembly, Temporal, cryptography, graphics, subprocesses, events, and Web APIs | | Testing, coverage, linting, and formatting | Tests, snapshots, retries, sharding, coverage, benchmarks, lint plugins, and formatting | | Type checking, tasks, CLI, and editor tooling | TypeScript configuration, checking, tasks, caching, upgrades, and language-server behavior |

Migrate breaking surfaces first

Replace removed commands and flags

• Remove deno vendor workflows.
• Do not assume deno bundle is still absent: it returned as an experimental esbuild-backed command with npm and JSR support.
• Replace deno cache <entrypoint> with deno install --entrypoint <entrypoint> when an explicit entry point must be cached.
• Remove obsolete --allow-hrtime, --allow-none, --trace-ops, --ts, generic --unstable, and --lock-write uses.
• Distinguish the removed generic --jobs flag from the later deno task --jobs workspace-concurrency option.
• Use feature-specific unstable flags or configuration entries where a feature remains gated.

Replace removed runtime APIs

• Replace Deno.run() with Deno.Command or the current subprocess APIs.
• Replace Deno.serveHttp() with Deno.serve().
• Replace Deno.isatty() with the applicable terminal property.
• Use Deno.FsFile methods, Web streams, and current filesystem helpers instead of removed resource IDs, Deno.File, Deno.Buffer, reader/writer interfaces, and resource-oriented free functions.
• Do not construct Deno.FsFile directly or read .rid properties.
• Move WebGPU window dimensions to the UnsafeWindowSurface constructor.
• Replace removed TLS certificate-file and certificate-chain option fields with current TLS options.

Reconcile stricter checking and configuration

• Unsupported compilerOptions now fail validation.
• Add override where noImplicitOverride requires it.
• Narrow caught values before use because catch variables are unknown.
• Do not use remote import maps or the removed files field in deno.json.
• Account for tsconfig.json discovery, project references, rootDirs, paths, types, extends, include, exclude, and per-workspace-member compiler options.
• Update Buffer and typed-array annotations when generic backing-buffer types expose ArrayBuffer versus SharedArrayBuffer differences.
• Do not remain on Deno 2.3.0 when its incorrect build metadata matters; upgrade to 2.3.1.

Recheck changed defaults

• Timer handles are Node-style NodeJS.Timeout objects, not numeric IDs.
• Run deno fmt . when formatting without discovered configuration or explicit files.
• Test operation and resource sanitizers default off; enable them when a suite relies on leak checks.
• Deno.serve() response compression is opt-in through automaticCompression or DENO_SERVE_AUTOMATIC_COMPRESSION.
• Deno.listenDatagram() defaults to 0.0.0.0; specify a hostname if binding all interfaces is undesirable.
• npm dependency resolution applies a default minimum release age unless configuration changes or disables it.
• Automatically decompressed responses retain content-encoding and content-length; the latter is not the decoded body size.

Manage dependencies deliberately

Choose the target manifest

• Let package commands use Deno's selected project manifest, or force package.json with --package-json.
• Set preferPackageJson when package-management commands should consistently target package.json.
• Package arguments without a registry prefix default to npm; use jsr: for JSR packages and explicit imports.
• Use --save-exact or --exact when the default caret range is too broad.
• Use .npmrc for scoped registries, authentication, mTLS, minimum release age, and trust-policy controls.

Install and update reproducibly

deno install
deno update
deno update --lockfile-only
deno ci

• deno ci requires a lockfile, removes node_modules, and enforces frozen resolution.
• deno install --lockfile-only resolves and updates the lock without fetching or installing packages.
• deno install --prod omits development dependencies and type packages.
• Use --os and --arch to resolve target-specific optional dependencies for another platform.
• Inspect declared dependencies with deno list and resolution paths with deno why.

Configure workspaces and local packages

• A workspace may combine deno.json and package.json members.
• Put shared versions in catalog or named catalogs; members use catalog: specifiers.
• Use links for local npm redirects; older patch configuration is deprecated.
• Choose isolated or hoisted node_modules through nodeModulesLinker based on tool expectations.
• Set jsrDepsInNodeModules only when Node-oriented tools need complete JSR tarballs and physical assets.

Build and distribute

Bundle or transpile

deno bundle --platform browser --outdir dist app.ts
deno transpile src/mod.ts --outdir dist --source-map separate --declaration

• Use deno bundle for a dependency graph; use deno transpile to strip types without bundling, rewriting modules, or loading project configuration.
• HTML bundle entries discover module scripts and global CSS and rewrite them to hashed assets.
• Use --declaration for rolled-up declaration output and --keep-names when generated names must remain stable.

Compile executables

deno compile --include assets/ --output app main.ts

• Use --include for resolved embedded assets and --include-as-is for verbatim files or directories.
• Put reusable asset selection under compile.include and compile.exclude in deno.json.
• Use --self-extracting when native add-ons or Node APIs need a real filesystem.
• Experimental --bundle with --minify can shrink npm-heavy executables through tree shaking.
• Set --app-name when compiled KV, local-storage, or Cache data needs stable application identity.

Package, publish, and deploy

• deno pack emits an npm tarball with transpiled exports, declarations, rewritten specifiers, and selected publish assets.
• Set "publish": false on private workspace members.
• Packages containing text or byte imports cannot be published.
• Deployment include and exclude filters select uploaded files, including workspace-member entries.

Test, lint, and format

deno check .
deno lint
deno fmt --check .
deno test --coverage

• Use lifecycle hooks, per-test timeouts, retries, repeats, parameterized cases, and built-in snapshots instead of recreating those mechanisms.
• Use --changed, --related, and --shard=<index>/<count> for selective or distributed test runs.
• Configure line, branch, and function coverage thresholds when CI must enforce minimums.
• Coverage can include ordinary deno run entry points and workers and can report function coverage.
• Configure lint plugins through lint.plugins; their selector, comment, fix, and permission surfaces are Deno-specific and not fully ESLint-compatible.
• Set explicit formatter policies for named-specifier sorting, JSON trailing commas, embedded languages, and .editorconfig precedence.

Use Node compatibility intentionally

• Deno can run ESM Node projects with package.json, npm workspaces, node_modules, and Node-API add-ons under Deno permissions.
• Let .js CommonJS detection follow the nearest package.json; enable compatibility fallback only when automatic detection is insufficient.
• Prefer node: for built-in imports even though bare built-ins now resolve without a flag.
• Expect global Buffer, global, setImmediate, and clearImmediate, plus Node-style timer handles.
• Check the Node reference before adding shims: filesystem, workers, IPC, module hooks, VM modules, networking, TLS, SQLite, tests, diagnostics, and cryptography have expanded.
• Use synchronous module.registerHooks() for supported custom resolution and loading; the deprecated module.register() API is intentionally unavailable.

Keep permissions and supply-chain controls narrow

{
  "permissions": {
    "local-data": { "read": ["./data"], "write": ["./data"] }
  }
}

deno run -P=local-data main.ts
deno audit

• Named permission sets are never selected implicitly; opt in with -P.
• Use --ignore-read or --ignore-env when a dependency should observe a denied resource as absent.
• DENO_TRACE_PERMISSIONS is diagnostic and expensive; DENO_AUDIT_PERMISSIONS records checks.
• Use deno approve-scripts for explicit persisted lifecycle-script trust.
• Combine audits, vulnerability fixes, minimum release age, and trust-policy=no-downgrade according to the project threat model.
• An active permission broker replaces CLI allow, deny, and ignore flags.

Operate servers and telemetry

• Configure DENO_SERVE_ADDRESS, DENO_AUTO_SERVE, --open, startup callbacks, backlog, and explicit compression for the hosting environment.
• Custom Deno.HttpClient transports support Unix sockets, Linux vsock, proxies, and bound local addresses; grant network permission where required.
• Happy Eyeballs connection racing is on by default; disable it only when the environment requires sequential address-family selection.
• Deno-specific WebSockets can send custom headers or use an HTTP client, unlike browser WebSocket constructors.
• Enable built-in OpenTelemetry with OTEL_DENO; select OTLP or console output and configure sampling and limits with the documented environment variables.
• Protect inspector captures, CPU profiles, permission logs, and TLS session-key logs because they can contain sensitive data.

Use modern runtime features

• Use stable Temporal directly.
• Import Wasm as a typed module, or use source-phase syntax for a compiled WebAssembly.Module.
• Text import attributes are stable; byte and CSS imports retain stability gates.
• Prefer using for disposable resources when lexical cleanup fits.
• Transfer streams, requests, and responses rather than serializing them when worker ownership can move.
• Feature-detect newer cryptographic algorithms with SubtleCrypto.supports().
• Use Web Locks for named shared or exclusive coordination scoped to an async callback.

Automate tasks and editor workflows

• Object-form tasks can declare descriptions and dependencies; dependencies run first and shared dependencies run once.
• Add files and output to cache deterministic tasks, including every environment input that affects the result.
• Control workspace parallelism with deno task --jobs; use --if-present, wildcards, exclusions, and --env-file as needed.
• Run deno check without arguments for the current project, --watch for continuous checking, and --check-js for JavaScript without file comments.
• Expect project-local formatting and compiler settings to affect the language server and auto-import discovery.
• Verify upgrades by checksum when required; prefer stable runtime artifacts over pull-request builds for production.

Treat desktop support as experimental

• Use deno desktop only when experimental APIs and packaging are acceptable.
• Choose the operating-system webview for smaller native integration or CEF for a bundled, consistent browser engine.
• Read the desktop reference before using windows, trays, docks, dialogs, bindings, deep links, auto-update, cross-target packaging, or framework adapters.