Deno 2 Apps skill for Codex

Done well means: the app runs with the narrowest permissions that work (never -A in production), dependencies are declared in deno.json and locked in deno.lock, type checking, formatting and linting run in CI, and the deploy target is the current Deno Deploy, not the retired Classic platform.

Before changing anything

1. Read AGENTS.md, deno.json / deno.jsonc (imports, tasks, permissions, nodeModulesDir, compilerOptions), any package.json, and deno.lock.
2. deno --version. These instructions assume Deno 2.x; Deno 1 projects need the migration notes below first.
3. Baseline: deno task (lists tasks), deno check ., deno lint, deno test -P. First runs download modules and need network; in an offline sandbox, use the cached DENO_DIR or ask before allowing network.

Configuration

{
  "tasks": {
    "dev": "deno serve --watch -P=server main.ts",
    "start": "deno serve -P=server main.ts",
    "check": "deno fmt --check && deno lint && deno check . && deno test -P"
  },
  "imports": {
    "@std/assert": "jsr:@std/assert@^1",
    "@std/http": "jsr:@std/http@^1",
    "hono": "jsr:@hono/hono@^4",
    "zod": "npm:zod@^3"
  },
  "permissions": {
    "server": {
      "net": ["0.0.0.0:8000", "api.stripe.com:443"],
      "env": ["DATABASE_URL", "STRIPE_KEY", "PORT"],
      "read": ["./static"]
    }
  },
  "test": { "permissions": { "read": ["./fixtures"], "env": true } },
  "lock": { "frozen": true }
}

• deno add jsr:@std/assert npm:zod updates imports for you; deno outdated lists upgrades.
• Prefer JSR for packages published there (typed, ESM, provenance); use npm: otherwise.
• "lock": { "frozen": true } (or --frozen) makes CI fail if deno.lock would change.
• Named permission sets need Deno 2.5 or later; on older 2.x, write the flags in each task.

Permissions

Flag	Scope it to	Example
--allow-net	Host and port	--allow-net=0.0.0.0:8000,api.example.com
--allow-read / --allow-write	Paths	--allow-read=./static --allow-write=./tmp
--allow-env	Variable names	--allow-env=DATABASE_URL,PORT
--allow-run	Executables	--allow-run=git (grants a lot; spawned processes are not sandboxed)
--allow-ffi, --allow-sys	Avoid unless required	FFI escapes the sandbox entirely
--deny-*	Carve exceptions	--allow-read --deny-read=/etc

Workflow to tighten an -A app:

1. Run the test suite and the app without -A. Deno prompts or throws NotCapable / PermissionDenied naming the exact resource.
2. Add each needed resource to a permission set, scoped as narrowly as the table shows.
3. Re-run until clean, then set DENO_NO_PROMPT=1 in CI so missing permissions fail instead of waiting for input.
4. Remember npm dependencies run under the same permissions: an SDK that reads unrelated env vars will need them listed or will fail at startup.

Serving HTTP

// main.ts, run with: deno serve -P=server main.ts
export default {
  async fetch(req) {
    const url = new URL(req.url);
    if (url.pathname === "/healthz") return new Response(null, { status: 204 });
    if (req.method === "POST" && url.pathname === "/api/orders") {
      const body = await req.json();
      return Response.json(await createOrder(body), { status: 201 });
    }
    return Response.json({ error: "not found" }, { status: 404 });
  },
} satisfies Deno.ServeDefaultExport;

Or programmatically, with graceful shutdown:

const ac = new AbortController();
const server = Deno.serve({ port: Number(Deno.env.get("PORT") ?? 8000), signal: ac.signal }, handler);
Deno.addSignalListener("SIGTERM", () => ac.abort());
await server.finished;

deno serve --parallel runs one worker per CPU core for the default-export form. For routing beyond a handful of paths, use Hono from JSR or @std/http route.

Node and npm compatibility

• Import built-ins with the node: prefix (import fs from "node:fs/promises").
• With a package.json, Deno reads its dependencies; set "nodeModulesDir": "auto" when a tool expects a real node_modules (bundlers, Prisma, packages that read their own files at runtime). "manual" means you run deno install or npm install yourself.
• npm lifecycle scripts do not run by default. Allow specific packages: deno install --allow-scripts=npm:sharp.
• CommonJS loads from .cjs files or packages marked "type": "commonjs"; require in an ESM .js file fails.
• Frameworks: Next.js, Astro, SvelteKit, Express and Fastify run with nodeModulesDir set; verify with the project’s own test suite rather than assuming.

Testing and quality

import { assertEquals, assertRejects } from "@std/assert";

Deno.test("createOrder rejects zero quantity", async () => {
  await assertRejects(() => createOrder({ sku: "A1", quantity: 0 }), RangeError);
});

Deno.test("total sums lines", async (t) => {
  await t.step("empty", () => assertEquals(total([]), 0));
  await t.step("two lines", () => assertEquals(total([{ q: 2, p: 5 }, { q: 1, p: 3 }]), 13));
});

deno test -P                  # uses "test.permissions" from deno.json
deno test --coverage=cov && deno coverage cov
deno fmt --check && deno lint && deno check .

deno run and deno serve do not type-check by default; keep deno check . in CI.

Compile and deploy

deno compile -P=server --include ./static -o dist/app main.ts

Permissions are baked into the compiled binary; review them before distributing.

Deno Deploy: Deploy Classic (dash.deno.com) and deployctl are retired in favour of the current platform at console.deno.com and the deno deploy subcommand, with the GitHub integration as the usual path. Classic projects do not migrate automatically; they are recreated as new apps. Deploying is a production action: confirm the target organization, app and environment with the user before running any deploy command, and set secrets in the dashboard per context (production, development, build) rather than in code.

Migrating from Deno 1

• deno.land/x URL imports still work, but move to JSR or npm via imports.
• Removed APIs (Deno.run, Deno.readAll, several Deno.* stream helpers) need Deno.Command and Web streams; deno lint flags many of them.
• window is gone; use globalThis.

Checklist

• No -A in tasks used for production; permission sets scoped
• Dependencies in imports; deno.lock committed and frozen in CI
• deno fmt --check, deno lint, deno check ., deno test -P pass
• SIGTERM handled; deploy target is the current Deno Deploy

Gotchas

• --allow-net without a value grants every host, including cloud metadata endpoints.
• --allow-run plus --allow-write effectively grants everything; treat it as -A.
• Deno.openKv() locally needs --unstable-kv; check KV availability on your Deploy plan before building on it.
• deno serve expects a default export; a file that calls Deno.serve itself must be run with deno run.