Deno Runtime skill for Claude Code

Done well means: no task runs with -A, each permission is scoped to the paths, hosts, env vars and binaries actually used, dependencies are pinned in deno.json with a committed deno.lock, and deno check, deno lint, deno fmt --check and deno test all pass in CI.

Workflow

- [ ] 1. Inventory the Deno version, config and dependency sources
- [ ] 2. Define tasks and imports in deno.json; commit deno.lock
- [ ] 3. Derive least-privilege permissions and encode them in config
- [ ] 4. Write the server or script on web-standard APIs
- [ ] 5. Test with Deno.test, sanitizers on, permissions scoped
- [ ] 6. Ship via deno compile, a container, or Deno Deploy

1. Inventory

deno --version
cat deno.json deno.jsonc package.json 2>/dev/null
deno info main.ts | head -40        # dependency graph: jsr:, npm:, https:, local
grep -rn "deno.land/std" --include=*.ts . | head   # legacy std imports to migrate

Record: Deno 2 minor (2.5 added permission sets in config, 2.6 more granular permissions and deno audit, 2.7 stabilized the Temporal API, 2.9 shipped June 2026), whether the project is package.json-driven or deno.json-driven, and any https:// imports. Migrate deno.land/std URLs to jsr:@std/* when touching those files.

2. deno.json

{
  "tasks": {
    "dev": "deno run --watch -P main.ts",
    "start": "deno run -P main.ts",
    "test": "deno test -P",
    "check": "deno check . && deno lint && deno fmt --check"
  },
  "imports": {
    "@std/assert": "jsr:@std/assert@^1.0.0",
    "@std/http": "jsr:@std/http@^1.0.0",
    "zod": "npm:zod@^4.0.0"
  },
  "permissions": {
    "default": {
      "net": ["0.0.0.0:8000", "api.stripe.com:443", "db.internal:5432"],
      "env": ["DATABASE_URL", "STRIPE_KEY", "PORT"],
      "read": ["./static"]
    }
  },
  "test": {
    "permissions": { "read": ["./fixtures"], "env": ["DATABASE_URL"] }
  },
  "lint": { "rules": { "tags": ["recommended"] } },
  "fmt": { "lineWidth": 100 }
}

deno add jsr:@std/path npm:pg       # writes to imports with a caret range
deno remove npm:pg
deno install                        # install everything (also reads package.json)
deno outdated                       # then update ranges deliberately
deno install --frozen               # CI: fail if deno.lock would change

• -P with no value applies the default permission set; -P=name or --permission-set=name applies a named one (Deno 2.5+). Once test.permissions exists, deno test must be run with -P or explicit flags.
• On Deno older than 2.5, write the scoped flags into each task string instead.
• nodeModulesDir: leave unset (global cache) for pure Deno apps; set "auto" when a framework or tool expects a real node_modules (Vite, Next-style tooling, packages that resolve files from disk), "manual" when another package manager owns it.
• npm lifecycle scripts do not run by default; allow specific ones with deno install --allow-scripts=npm:<pkg> only after reviewing what they do.

3. Least-privilege permissions

Need	Flag (scoped)	Avoid
Listen on a port	--allow-net=0.0.0.0:8000	--allow-net
Call specific APIs	--allow-net=api.example.com:443	wildcard hosts
Read config/static files	--allow-read=./static,./config	--allow-read on /
Write output	--allow-write=./out	--allow-write
Env vars	--allow-env=DATABASE_URL,PORT	--allow-env
Spawn a binary	--allow-run=git	--allow-run (equals full access)
FFI / native addons	--allow-ffi=./lib/libfoo.so	blanket --allow-ffi
Block something inside a broad allow	--deny-net=169.254.169.254	relying on review alone

Derivation loop:

1. Run with no permissions in a terminal; Deno prompts for each access. Note every request, or set DENO_AUDIT_PERMISSIONS=./perm-audit.jsonl (2.5+) to log checks.
2. Encode the minimal set in deno.json permissions or task flags.
3. Add --no-prompt (non-interactive contexts already fail instead of prompting) so a missing permission fails loudly rather than hanging.
4. Treat --allow-run, --allow-ffi, unscoped --allow-write and --allow-env as equivalent to -A; justify each in a comment or the PR.
5. Deny cloud metadata endpoints (169.254.169.254) when net access is broad.

4. Server code

// main.ts
import { z } from "zod";

const Order = z.object({ sku: z.string().min(1), qty: z.number().int().min(1).max(99) });

export default {
  async fetch(req: Request): Promise<Response> {
    const url = new URL(req.url);
    if (req.method === "GET" && url.pathname === "/healthz") return new Response("ok");
    if (req.method === "POST" && url.pathname === "/orders") {
      const parsed = Order.safeParse(await req.json().catch(() => null));
      if (!parsed.success) return Response.json(z.flattenError(parsed.error), { status: 422 });
      return Response.json({ id: crypto.randomUUID(), ...parsed.data }, { status: 201 });
    }
    return new Response("not found", { status: 404 });
  },
} satisfies Deno.ServeDefaultExport;

deno serve -P --port 8000 main.ts           # uses the default export
deno serve -P --parallel main.ts            # one worker per core

Or call Deno.serve({ port: 8000, signal }, handler) directly; pass an AbortSignal and abort it on SIGTERM (Deno.addSignalListener("SIGTERM", ...)) to drain cleanly. Hono, Oak and Fresh run on Deno when a framework is wanted.

Node compatibility: node: built-ins and most npm packages work. CommonJS loads from .cjs files or packages with "type": "commonjs"; require is not available in ESM .ts files (use createRequire from node:module if needed). Globals like process and Buffer exist in npm packages; in your own code import them from node:process and node:buffer for clarity.

5. Tests

import { assertEquals, assertRejects } from "@std/assert";
import handler from "./main.ts";

Deno.test("POST /orders validates qty", async (t) => {
  await t.step("rejects qty 0", async () => {
    const res = await handler.fetch(new Request("http://x/orders", {
      method: "POST",
      body: JSON.stringify({ sku: "A1", qty: 0 }),
    }));
    assertEquals(res.status, 422);
    await res.body?.cancel();        // unconsumed bodies trip the resource sanitizer
  });
});

deno test -P --coverage=cov
deno coverage cov --lcov > cov.lcov
deno test -P --filter "orders" --fail-fast

• Sanitizers fail tests that leak timers, open files, or unconsumed response bodies. Fix the leak; disable sanitizeOps/sanitizeResources per test only for a documented third-party leak.
• @std/testing provides bdd (describe/it), mock (stub, spy) and time (FakeTime). Deno 2.5+ also has Deno.test.beforeAll/beforeEach/afterAll/ afterEach hooks.
• Tests get only the permissions you pass; a test that needs the network must say so.

6. Ship

Target	Command / approach
Single binary	deno compile -P --output app main.ts; cross-compile with --target x86_64-unknown-linux-gnu. Permissions are baked in at compile time
Container	FROM denoland/deno:<exact-version>, RUN deno install --frozen, run deno run -P main.ts as the deno user
Deno Deploy (GA since Feb 2026)	Connect the GitHub repo or use the deploy CLI described in current Deploy docs; set env vars in the dashboard; no local filesystem writes
JSR package	deno publish --dry-run, then deno publish; requires name, version, exports in deno.json

Deploy tooling changed during 2025 (the classic deployctl flow was replaced by the new Deploy platform). Check the current docs before writing CI steps instead of copying older examples.

Gotchas

• deno.lock must be committed; without it, caret ranges float between machines.
• --allow-net without a port allows every port on that host.
• Remote https:// imports need --allow-import for hosts outside Deno’s default allowlist; prefer JSR or npm specifiers over raw URLs.
• deno check is separate from deno run; type errors do not stop deno run unless --check is passed.
• Deno.openKv() and other unstable APIs need the matching --unstable-* flag or "unstable": ["kv"] in deno.json.

Verification

deno install --frozen
deno task check                  # deno check . && deno lint && deno fmt --check
deno test -P
grep -n '"-A"\|--allow-all\| -A ' deno.json   # must return nothing

Run the production command once with a permission removed (e.g. drop one env var from the set) and confirm it fails with a clear NotCapable error rather than misbehaving; that proves the permission boundary is real.