denoland avatar

deno-skills

Modern Deno development knowledge: dependency management, npm and JSR packages, permissions, the built-in toolchain, migrating from Node/npm/yarn/pnpm/bun, Fresh, and Deno Deploy

version
2.0.0
GitHub stars
103

Install

/plugin install deno-skills@denoland-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add denoland/skills.

Contents

Discovered from source

Skills 5

Deno Deploy

This skill provides guidance for deploying applications to Deno Deploy.

Scope Boundaries

This skill applies only to Deno Deploy questions. Follow these rules:

  • If the user asks about AWS Lambda, Vercel, Netlify, Google Cloud Run, Docker, Kubernetes, or any other deployment platform, answer using that platform directly. Do not mention Deno Deploy at all — not as an alternative, not as a comparison, not as a suggestion.
  • If the user asks about running a local Deno script (not deploying), answer the local question directly. Do not mention Deno Deploy, deployment, or the --tunnel flag.
  • Do not include deno deploy commands, Deno KV, or Deno Deploy environment variable configuration in responses about other platforms or local-only scripts.
  • Only discuss Deno Deploy when the user explicitly asks about Deno Deploy or deploying a Deno application to production.

Important: Use deno deploy, NOT deployctl

Always use the deno deploy command. Do NOT use deployctl.

  • deployctl is for Deno Deploy Classic (deprecated)
  • deno deploy is the modern, integrated command built into the Deno CLI
  • Requires Deno >= 2.4.2 - the deno deploy subcommand was introduced in Deno 2.4

When Unsure About CLI Flags

Always run --help before guessing at flags. The deno deploy subcommand has many flags, and they change between versions. When you're unsure what a command accepts:

# See all subcommands
deno deploy --help

# See flags for a specific subcommand
deno deploy create --help
deno deploy env --help
deno deploy database --help

This takes seconds and prevents repeated trial-and-error failures. Never assume a flag exists — check first.

Deployment Workflow

Always show the core deploy command first — then explain diagnostic steps. When a user asks "how do I deploy?", lead with the actual command (deno deploy --prod) before covering pre-flight checks and configuration.

Step 1: Locate the App Directory

Before running any deploy commands, find where the Deno app is located:

# Check if deno.json exists in current directory
if [ -f "deno.json" ] || [ -f "deno.jsonc" ]; then
  echo "APP_DIR: $(pwd)"
else
  # Look for deno.json in immediate subdirectories
  find . -maxdepth 2 -name "deno.json" -o -name "deno.jsonc" 2>/dev/null | head -5
fi

All deploy commands must run from the app directory.

Step 2: Pre-Flight Checks

Check Deno version and existing configuration:

# Check Deno version (must be >= 2.4.2)
deno --version | head -1

# Check for existing deploy config
grep -E '"org"|"app"' deno.json deno.jsonc 2>/dev/null || echo "NO_DEPLOY_CONFIG"

Step 3: Check for Startup Dependencies

Before deploying, check if the app connects to a database or external service at startup (e.g., top-level await initDb() in main.ts). If it does, the deploy will fail during warmup because the database doesn't exist yet.

If the app has startup database dependencies, follow this order:

  1. Create the app with --no-wait so a warmup failure doesn't block you:

    deno deploy create \
      --org <ORG_NAME> --app <APP_NAME> \
      --source local --runtime-mode dynamic --entrypoint main.ts \
      --build-timeout 5 --build-memory-limit 1024 --region us \
      --no-wait
    
  2. Provision and assign the database:

    deno deploy database provision my-db --kind prisma --region us-east-1
    deno deploy database assign my-db --app <APP_NAME>
    
  3. Redeploy (now the database exists, warmup will succeed):

    deno deploy --prod
    

If the app has no startup dependencies, skip this step and deploy normally below.

Step 4: Deploy Based on Configuration

If deploy.org AND deploy.app exist in deno.json:

# Build if needed (Fresh, Astro, etc.)
deno task build

# Deploy to production
deno deploy --prod

If NO deploy config exists:

Apps must be created before they can be deployed to. You cannot run deno deploy --prod until an app exists.

IMPORTANT: Ask the user first - Do they have an existing app on Deno Deploy, or do they need to create a new one?

If they have an existing app, add the config directly to deno.json:

{
  "deploy": {
    "org": "<ORG_NAME>",
    "app": "<APP_NAME>"
  }
}

The org name is in the Deno Deploy console URL (e.g., console.deno.com/your-org-name). Once this config is in place, subsequent deploys just need deno deploy --prod.

If they need to create a new app:

The CLI needs an organization name. Find it at https://console.deno.com - the org is in the URL path (e.g., console.deno.com/your-org-name).

Interactive creation (opens a browser — only works when a human is at the keyboard):

deno deploy create --org <ORG_NAME>
# A browser window opens - complete the app creation there

Non-interactive creation (use when an AI agent is performing the deploy, or in CI/CD):

deno deploy create \
  --org <ORG_NAME> \
  --app <APP_NAME> \
  --source local \
  --runtime-mode dynamic \
  --entrypoint main.ts \
  --build-timeout 5 \
  --build-memory-limit 1024 \
  --region us

The create command also does the initial deploy. After it completes, deno.json is updated with deploy.org and deploy.app automatically. From that point on, subsequent deploys only need:

deno deploy --prod

After completion, verify the config was saved:

grep -E '"org"|"app"' deno.json

When an AI agent is performing the deployment, always use the non-interactive flow with explicit flags. The interactive flow requires browser windows and terminal prompts that agents cannot navigate.

Core Commands

Production Deployment

deno deploy --prod

Preview Deployment

deno deploy

Preview deployments create a unique URL for testing without affecting production.

Targeting Specific Apps

deno deploy --org my-org --app my-app --prod

Configuring an Entrypoint

Set the entrypoint in your deno.json (this is used by deno deploy create during app creation):

{
  "deploy": {
    "entrypoint": "main.ts"
  }
}

Note: --entrypoint is a flag on deno deploy create, not on deno deploy itself.

Additional Flags

These flags are available on deno deploy create (and apply during the initial deploy):

FlagPurpose
--allow-node-modulesInclude node_modules directory in upload
--no-waitSkip waiting for the build to complete

Creating Apps (Non-Interactive Reference)

When any flag beyond --org is provided, deno deploy create runs in non-interactive mode — all required flags must be specified. This is the recommended approach for AI agents and CI/CD pipelines.

Required Flags

FlagDescription
--org <name>Organization name
--app <name>Application name (becomes your URL: <app>.deno.dev)
--source <local|github>Deploy from local files or a GitHub repo
--build-timeout <minutes>Build timeout: 5, 10, 15, 20, 25, or 30
--build-memory-limit <MB>Memory limit: 1024, 2048, 3072, or 4096
--region <region>Deployment region: us, eu, or global

GitHub Source Flags

When using --source github, you also need:

FlagDescription
--owner <name>GitHub repository owner
--repo <name>GitHub repository name

Build Configuration Flags

FlagDescription
--app-directory <path>Path to app directory (for monorepos)
--framework-preset <preset>Framework preset (see Frameworks)
--install-command <cmd>Custom install command
--build-command <cmd>Custom build command
--pre-deploy-command <cmd>Command to run before deploy
--do-not-use-detected-build-configSkip auto-detection of framework config

The CLI auto-detects your framework and build configuration. If a framework is detected, you can skip --install-command, --build-command, --pre-deploy-command, and --runtime-mode — they'll be inferred from the preset. Use --do-not-use-detected-build-config to override detection. When using this flag, all three build commands (--install-command, --build-command, --pre-deploy-command) plus --runtime-mode become required — omitting any of them causes exit code 2.

Runtime Mode Flags

You must pick a runtime mode with --runtime-mode <dynamic|static> (unless a framework preset handles it).

Dynamic mode (for apps with a server):

FlagDescription
--entrypoint <path>Entry file (required for dynamic mode)
--arguments <args>Arguments passed to entrypoint (repeatable)
--working-directory <cwd>Working directory for the process

Static mode (for static sites):

FlagDescription
--static-dir <dir>Directory to serve static files from (required)
--single-page-appServe index.html for routes that don't match a file

Other Flags

FlagDescription
--dry-runValidate everything without actually creating the app
--no-waitDon't wait for the build to complete
--allow-node-modulesInclude node_modules in the upload

Examples

Simple Deno server:

deno deploy create \
  --org my-org --app my-api \
  --source local \
  --runtime-mode dynamic --entrypoint main.ts \
  --build-timeout 5 --build-memory-limit 1024 --region us

Fresh app (framework auto-detected):

deno deploy create \
  --org my-org --app my-fresh-app \
  --source local \
  --build-timeout 5 --build-memory-limit 1024 --region us

Next.js from GitHub:

deno deploy create \
  --org my-org --app my-next-app \
  --source github --owner my-github-user --repo my-next-repo \
  --framework-preset Next \
  --build-timeout 15 --build-memory-limit 2048 --region us \
  --allow-node-modules

Static site:

deno deploy create \
  --org my-org --app my-static-site \
  --source local \
  --runtime-mode static --static-dir dist --single-page-app \
  --build-command "deno task build" \
  --build-timeout 5 --build-memory-limit 1024 --region us

Environment Variables

Contexts

Deno Deploy has three "contexts" - logical environments where your code runs, each with its own set of variables:

ContextPurpose
ProductionLive traffic on your production URL
DevelopmentPreview deployments and branch URLs
BuildOnly available during the build process

You can set different values for the same variable in each context. For example, you might use a test database URL in Development and the real one in Production.

Predefined Variables

These are automatically available in your code:

VariableDescription
DENO_DEPLOYAlways 1 when running on Deno Deploy
DENO_DEPLOYMENT_IDUnique ID for the current deployment
DENO_DEPLOY_ORG_IDYour organization's ID
DENO_DEPLOY_APP_IDYour application's ID
CISet to 1 during builds only

Accessing Variables in Code

const dbUrl = Deno.env.get("DATABASE_URL");
const isDenoDeploy = Deno.env.get("DENO_DEPLOY") === "1";

Managing Variables via CLI

# Add a plain text variable
deno deploy env add DATABASE_URL "postgres://..."

# Add a secret variable (hidden after creation, only readable in code)
deno deploy env add API_KEY "sk-..." --secret

# List all variables
deno deploy env list

# Update just the value (keeps contexts and secret status)
deno deploy env update-value DATABASE_URL "postgres://new-url..."

# Update which contexts a variable applies to
deno deploy env update-contexts DATABASE_URL production development

# Delete a variable
deno deploy env delete DATABASE_URL

# Load from .env file (all values treated as secrets by default)
deno deploy env load .env.production

# Load from .env file, marking specific keys as non-secrets
deno deploy env load .env.production --non-secrets PUBLIC_URL APP_NAME

Variable Types

  • Plain text - Visible in the dashboard, good for feature flags and non-sensitive config
  • Secrets - Hidden after creation, only readable in your code, use for API keys and credentials

Limits

  • Key names: max 128 bytes
  • Values: max 16 KB
  • Keys cannot start with DENO_, LD_, or OTEL_

Viewing Logs

# Stream live logs
deno deploy logs

# Filter by date range
deno deploy logs --start 2026-01-15 --end 2026-01-16

Databases & Storage

Deno Deploy provides built-in database support with automatic environment isolation. Each environment (production, preview, branch) gets its own isolated database automatically.

Available Options

EngineUse Case
Deno KVKey-value storage, simple data, counters, sessions
PostgreSQLRelational data, complex queries, existing Postgres apps

Deno KV Quick Start

No configuration needed - just use the built-in API:

const kv = await Deno.openKv();

// Store data
await kv.set(["users", "alice"], { name: "Alice", role: "admin" });

// Retrieve data
const user = await kv.get(["users", "alice"]);
console.log(user.value); // { name: "Alice", role: "admin" }

// List by prefix
for await (const entry of kv.list({ prefix: ["users"] })) {
  console.log(entry.key, entry.value);
}

Deno Deploy automatically connects to the correct database based on your environment.

PostgreSQL

For PostgreSQL, Deno Deploy injects environment variables (DATABASE_URL, PGHOST, etc.) that most libraries detect automatically:

// Recommended: npm:pg (best PostgreSQL driver for Deno Deploy)
import pg from "npm:pg";
const pool = new pg.Pool(); // Reads DATABASE_URL from environment automatically

Provisioning

Use the deno deploy database command to provision and manage databases:

# Provision a Deno KV database
deno deploy database provision my-database --kind denokv

# Provision a Prisma PostgreSQL database
deno deploy database provision my-database --kind prisma --region us-east-1

# Assign to your app
deno deploy database assign my-database --app my-app

For detailed CLI commands, see Databases.

Local Development

Use --tunnel to connect to your hosted development database locally:

deno task --tunnel dev

See Databases and Deno KV for detailed documentation.

Local Development Tunnel

The tunnel feature lets you expose your local development server to the internet. This is useful for:

  • Testing webhooks - Receive webhook callbacks from external services
  • Sharing with teammates - Let others preview your local work
  • Mobile testing - Access your local server from other devices

Basic Usage

Add the --tunnel flag when running your app:

deno run --tunnel -A main.ts

The first time you run this, it will:

  1. Ask you to authenticate with Deno Deploy (opens a browser)
  2. Ask you to select which app to connect the tunnel to
  3. Generate a public URL that forwards requests to your local server

Using with Tasks

You can use --tunnel with your existing tasks in deno.json:

deno task --tunnel dev

This runs your dev task with the tunnel enabled.

What the Tunnel Provides

Beyond just forwarding requests, the tunnel also:

  • Syncs environment variables - Variables set in your Deno Deploy app's "Local" context become available to your local process
  • Sends logs and metrics - OpenTelemetry data goes to the Deno Deploy dashboard (filter with context:local)
  • Connects to databases - Automatically connects to your assigned local development databases

Managing Tunnels

  • View active tunnels in the Deno Deploy dashboard under the "Tunnels" tab
  • Stop a tunnel by terminating the Deno process (Ctrl+C)

Command Reference

CommandPurpose
deno deploy --prodDeploy to production (app must exist first)
deno deployPreview deployment
deno deploy create --org <name>Create new app (interactive)
deno deploy create --org <name> --app <name> ...Create new app (non-interactive, see full flags above)
deno deploy create ... --no-waitCreate app without waiting for build to complete
deno deploy create ... --allow-node-modulesCreate app including node_modules
deno deploy env add <var> <value>Add plain text environment variable
deno deploy env add <var> <value> --secretAdd secret environment variable
deno deploy env listList environment variables
deno deploy env update-value <var> <value>Update variable value (keeps contexts/secret status)
deno deploy env update-contexts <var> <contexts...>Update which contexts a variable applies to
deno deploy env delete <var>Delete environment variable
deno deploy env load <file>Load variables from .env file (defaults to secret)
deno deploy env load <file> --non-secrets <keys...>Load .env file, marking specific keys as non-secrets
deno deploy database provision <name> --kind <type>Provision a new database
deno deploy database assign <name> --app <app>Assign database to an app
deno deploy logsView deployment logs
deno run --tunnel -A <file>Start local tunnel
deno task --tunnel <task>Run task with tunnel

Edge Runtime Notes

Deno Deploy runs in one or many regions (globally distributed). Keep in mind:

  • Environment variables - Must be set via deno deploy env, not .env files at runtime
  • Global distribution - Code runs at the region closest to users
  • Cold starts - First request after idle may be slightly slower

Additional References

Documentation

Frontend development with Deno

Two paths. Pick by what the project already uses.

Regular npm frameworks — the usual choice

Deno runs the normal frontend ecosystem: React, Vue, Svelte, Solid, Vite, Astro, Next.js, Nuxt, SvelteKit, Remix, SolidStart. Nothing needs to be ported, and there is no Deno-specific way to write them.

deno create vite my-app     # or astro, next, nuxt, svelte…
cd my-app
deno install
deno task dev

deno create is npm create. deno install reads package.json. deno task <script> runs package.json scripts. That is the whole difference.

Follow the framework's own documentation for everything else — routing, components, data loading, and config are the framework's concern, not Deno's. Don't invent Deno-flavoured variants of their APIs, and don't reach for Fresh patterns in a React or Svelte project.

The only things worth knowing:

  • Some frameworks need "nodeModulesDir": "auto" in deno.json; Next.js does.
  • Permissions apply to the dev server too — framework tasks generally want -A.
  • Deploying: see the deno-deploy skill, which lists per-framework build commands and presets.

Fresh — Deno's own framework

Fresh suits a new Deno-first project that wants server rendering with minimal client JavaScript. It uses island architecture: pages render on the server, and only components in islands/ ship JavaScript.

deno run -Ar jsr:@fresh/init
cd my-project
deno task dev                # http://localhost:5173

A Fresh project is Vite-based: vite.config.ts for the build, main.ts for the server, file-based routes in routes/, islands in islands/, server-only components in components/. Preact supplies the component model, with signals for state.

// islands/Counter.tsx — interactive, ships JS
import { useSignal } from "@preact/signals";

export default function Counter() {
  const count = useSignal(0);
  return <button onClick={() => count.value++}>Count: {count.value}</button>;
}

Three rules carry most of the weight:

  1. Islands ship JavaScript — keep them small, leave everything else in components/.
  2. Island props must be serializable. Functions cannot be passed.
  3. Handlers take a single (ctx) parameter.

Load references/FRESH.md for routes, handlers, define helpers, middleware, islands, signals, and Tailwind.

Use Fresh 2.x, imported from "fresh". For an existing 1.x project, or one pinned to a 2.0.0-alpha.* release, see references/FRESH_MIGRATION.md.

Further reading

  • https://fresh.deno.dev/docs — Fresh documentation
  • references/FRESH.md — Fresh 2.x patterns in depth
  • references/FRESH_MIGRATION.md — Fresh 1.x and alpha migration

Deno Sandboxes

Overview

Deno Sandboxes provide secure, isolated environments for running untrusted code. Each sandbox runs in its own Linux microVM (using Firecracker, the same technology as AWS Lambda) with a separate filesystem, network, and process space. This makes them ideal for code playgrounds, AI agent tool execution, and multi-tenant applications.

Reference: https://deno.com/deploy/sandboxes

When to Use Sandboxes

Use Deno Sandboxes when you need to:

  • Run user-submitted code safely
  • Execute AI-generated code
  • Build code playground platforms
  • Create multi-tenant code execution environments
  • Run automated tests in isolation

Scope Boundaries

This skill applies only to Deno Sandbox (@deno/sandbox) questions. Follow these rules:

  • If the user asks about Docker containers, Node.js vm2/vm, Web Workers, AWS Lambda isolation, or any other isolation technology, answer using that technology directly. Do not suggest Deno Sandboxes as an alternative.
  • Do not include @deno/sandbox imports, Sandbox.create(), or sandbox.spawn() in responses about other isolation technologies.
  • Only recommend Deno Sandboxes when the user explicitly asks about them or is building code execution features in a Deno project.

Getting Started

Installation

deno add jsr:@deno/sandbox

Basic Usage

import { Sandbox } from "@deno/sandbox";

// Create a sandbox (auto-disposed when scope ends)
await using sandbox = await Sandbox.create();

// Run a command
const child = await sandbox.spawn("echo", { args: ["Hello from sandbox!"] });
const output = await child.output();

console.log(new TextDecoder().decode(output.stdout));
// Output: Hello from sandbox!

Core Concepts

Sandbox Lifecycle

Sandboxes are resources that must be disposed when done. Always use await using for automatic cleanup:

await using sandbox = await Sandbox.create();
// Sandbox is automatically destroyed when this scope ends

CRITICAL: Never show const sandbox = await Sandbox.create() without await using. Always use the await using pattern for sandbox creation. Do not show manual disposal alternatives.

Running Processes

The spawn method runs commands inside the sandbox:

const child = await sandbox.spawn("deno", {
  args: ["run", "script.ts"],
  stdin: "piped", // Enable stdin
  stdout: "piped", // Capture stdout
  stderr: "piped", // Capture stderr
});

// Wait for completion and get output
const output = await child.output();
console.log("Exit code:", output.code);
console.log("Stdout:", new TextDecoder().decode(output.stdout));
console.log("Stderr:", new TextDecoder().decode(output.stderr));

Streaming I/O

For interactive processes or long-running commands:

const child = await sandbox.spawn("deno", {
  args: ["repl"],
  stdin: "piped",
  stdout: "piped",
});

// Write to stdin
const writer = child.stdin!.getWriter();
await writer.write(new TextEncoder().encode("console.log('Hello')\n"));
await writer.close();

// Read from stdout
const reader = child.stdout!.getReader();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(new TextDecoder().decode(value));
}

Killing Processes

const child = await sandbox.spawn("sleep", { args: ["60"] });

// Kill with SIGTERM (default)
await child.kill();

// Or with specific signal
await child.kill("SIGKILL");

// Wait for exit
const status = await child.status;
console.log("Exited with signal:", status.signal);

Common Patterns

Running User Code Safely

import { Sandbox } from "@deno/sandbox";

async function runUserCode(code: string): Promise<string> {
  await using sandbox = await Sandbox.create();

  // Write user code to a file in the sandbox
  await sandbox.fs.writeFile("/tmp/user_code.ts", code);

  // Run with restricted permissions
  const child = await sandbox.spawn("deno", {
    args: [
      "run",
      "--allow-none", // No permissions
      "/tmp/user_code.ts",
    ],
    stdout: "piped",
    stderr: "piped",
  });

  const output = await child.output();

  if (output.code !== 0) {
    throw new Error(new TextDecoder().decode(output.stderr));
  }

  return new TextDecoder().decode(output.stdout);
}

Code Playground

import { Sandbox } from "@deno/sandbox";

interface ExecutionResult {
  success: boolean;
  output: string;
  error?: string;
  executionTime: number;
}

async function executePlayground(code: string): Promise<ExecutionResult> {
  const start = performance.now();

  await using sandbox = await Sandbox.create();

  await sandbox.fs.writeFile("/playground/main.ts", code);

  const child = await sandbox.spawn("deno", {
    args: ["run", "--allow-net", "/playground/main.ts"],
    stdout: "piped",
    stderr: "piped",
  });

  const output = await child.output();
  const executionTime = performance.now() - start;

  return {
    success: output.code === 0,
    output: new TextDecoder().decode(output.stdout),
    error: output.code !== 0
      ? new TextDecoder().decode(output.stderr)
      : undefined,
    executionTime,
  };
}

AI Agent Tool Execution

import { Sandbox } from "@deno/sandbox";

async function executeAgentTool(
  toolCode: string,
  input: unknown,
): Promise<unknown> {
  await using sandbox = await Sandbox.create();

  // Create a wrapper that handles input/output
  const wrapper = `
    const input = ${JSON.stringify(input)};
    const tool = await import("/tool.ts");
    const result = await tool.default(input);
    console.log(JSON.stringify(result));
  `;

  await sandbox.fs.writeFile("/tool.ts", toolCode);
  await sandbox.fs.writeFile("/run.ts", wrapper);

  const child = await sandbox.spawn("deno", {
    args: ["run", "--allow-net", "/run.ts"],
    stdout: "piped",
    stderr: "piped",
  });

  const output = await child.output();

  if (output.code !== 0) {
    throw new Error(new TextDecoder().decode(output.stderr));
  }

  return JSON.parse(new TextDecoder().decode(output.stdout));
}

Sandbox Features

Resource Configuration

Sandboxes have configurable resources:

  • Default: 2 vCPUs, 512MB memory, 10GB disk
  • Startup time: Under 200ms

What's Included

Each sandbox comes with:

  • TypeScript/JavaScript runtime (Deno)
  • Full Linux environment
  • Network access (can be restricted)
  • Temporary filesystem

Security Features

  • Firecracker microVMs - Same technology as AWS Lambda
  • Full isolation - Separate kernel, filesystem, network
  • No data leakage - Sandboxes can't access host system
  • Enforced policies - Control outbound connections

Deploying Sandboxes

Sandboxes can be deployed directly to Deno Deploy:

deno deploy --prod

The sandbox SDK works seamlessly in the Deno Deploy environment.

API Reference

For the complete API, run:

deno doc jsr:@deno/sandbox

Key classes:

  • Sandbox - Main class for creating/managing sandboxes
  • ChildProcess - Represents a running process
  • Client - For managing Deploy resources (apps, volumes)

Quick Reference

TaskCode
Create sandboxawait using sandbox = await Sandbox.create()
Run commandsandbox.spawn("cmd", { args: [...] })
Get outputconst output = await child.output()
Write fileawait sandbox.fs.writeFile(path, content)
Read fileawait sandbox.fs.readFile(path)
Kill processawait child.kill()
Check statusconst status = await child.status

Common Mistakes

Forgetting automatic disposal

// ❌ Wrong - always use "await using" for sandbox creation
// Never write: const sandbox = await Sandbox.create() without "await using"

// ✅ Correct - use "await using" for automatic cleanup
await using sandbox = await Sandbox.create();
await sandbox.spawn("echo", { args: ["hello"] });
// sandbox automatically disposed when scope ends

Giving user code too many permissions

// ❌ Wrong - gives untrusted code full access
const child = await sandbox.spawn("deno", {
  args: ["run", "--allow-all", "/tmp/user_code.ts"],
});

// ✅ Correct - restrict permissions to what's needed
const child = await sandbox.spawn("deno", {
  args: ["run", "--allow-none", "/tmp/user_code.ts"], // No permissions
});

// Or if network is truly needed:
const child = await sandbox.spawn("deno", {
  args: ["run", "--allow-net", "/tmp/user_code.ts"], // Only network
});

Not handling process output properly

// ❌ Wrong - forgetting to pipe stdout/stderr
const child = await sandbox.spawn("deno", { args: ["run", "script.ts"] });
const output = await child.output();
// output.stdout is empty because we didn't pipe it!

// ✅ Correct - pipe the streams you need
const child = await sandbox.spawn("deno", {
  args: ["run", "script.ts"],
  stdout: "piped",
  stderr: "piped",
});
const output = await child.output();
console.log(new TextDecoder().decode(output.stdout));

Not setting timeouts for user code execution

// ❌ Wrong - user code could run forever
const child = await sandbox.spawn("deno", {
  args: ["run", "/tmp/user_code.ts"],
});
await child.output(); // Could hang indefinitely

// ✅ Correct - implement timeout handling
const child = await sandbox.spawn("deno", {
  args: ["run", "/tmp/user_code.ts"],
  stdout: "piped",
  stderr: "piped",
});

// Set a timeout to kill the process
const timeoutId = setTimeout(() => child.kill(), 5000); // 5 second limit

try {
  const output = await child.output();
  return output;
} finally {
  clearTimeout(timeoutId);
}

Trusting sandbox output without validation

// ❌ Wrong - directly using untrusted output as code
const result = await runUserCode(code);
// Never execute or inject untrusted output!

// ✅ Correct - validate and sanitize output
const result = await runUserCode(code);
try {
  const parsed = JSON.parse(result); // Parse as data, not code
  if (isValidResponse(parsed)) {
    return parsed;
  }
} catch {
  throw new Error("Invalid response from sandbox");
}

Deno

A JavaScript and TypeScript runtime with a package manager, formatter, linter, test runner, type checker, and bundler in one binary. Runs TypeScript directly.

Needs Deno 2.9+. Check with deno --version, update with deno upgrade.

Deno works the way npm and bun do

Deno is not a separate ecosystem to port code into:

  • deno install reads an existing package.json and writes a real node_modules.
  • deno add express installs from npm. Unprefixed names default to npm.
  • deno task build runs scripts.build from package.json or tasks.build from deno.json. If both define it, deno.json wins.
  • Node built-ins work prefixed or not: node:fs and fs both resolve.
  • deno main.js runs a file. deno run is optional.
  • Deno reads tsconfig.json.

Don't tell users to rewrite imports, adopt JSR, or restructure as a precondition. The two real differences are permissions and npm lifecycle scripts not running by default.

Single-file scripts need no build step and no tsconfig.json. Applications and framework projects keep their normal setup.

To convert an existing project, see the migrate-to-deno skill.

Dependency management

deno install                  # install everything declared
deno add express              # from npm (unprefixed = npm)
deno add jsr:@std/path        # from JSR
deno add -D vitest            # dev dependency (package.json only)
deno remove express
deno outdated                 # list outdated deps
deno update                   # alias for `deno outdated --update`
deno update --latest          # ignore existing semver ranges
deno list                     # declared deps + resolved versions (npm ls)
deno why express              # why a package is in the tree
deno audit                    # vulnerability audit
deno ci                       # clean reproducible install for CI
dx cowsay hello               # run a package binary without installing (npx)

deno ci is the CI command, not deno install: it requires deno.lock, deletes node_modules, installs strictly from the lockfile, and fails if the lockfile is stale. --prod skips devDependencies.

dx is npx / bunx / pnpm dlx, and an alias for deno x. It runs with the sandbox disabled, so treat it with the same care as npx.

Deno won't install a version published less than a day ago, limiting the window for a compromised release. Override with --min-dep-age, which takes minutes (120), an ISO-8601 duration (P7D), a cutoff date, or 0 to disable:

deno add --min-dep-age=0 npm:some-package

Lifecycle scripts (postinstall) don't run by default — a common surprise when a native addon looks broken after install. Approve once per project:

deno approve-scripts                              # interactive picker
deno install --allow-scripts=npm:better-sqlite3

Where configuration goes

FileHolds
package.jsondependencies, scripts
tsconfig.jsonTypeScript compiler options
deno.jsonDeno config: fmt, lint, tasks, workspaces

Put dependencies in package.json — every other tool reads it, and Deno resolves it natively. Use deno.json for dependencies only when there is no package.json: a standalone script, or a JSR package. Likewise prefer tsconfig.json over compilerOptions in deno.json, so tsc and editors see the same settings.

Commit deno.lock. Deno seeds it from an existing package-lock.json, yarn.lock, bun.lock, or pnpm lockfile, preserving pins.

node_modules layout

Deno uses pnpm's isolated layout: real files in node_modules/.deno/, exposed by symlinks, so a package can't import what it never declared. For a tool that needs npm's flat hoisted tree:

{ "nodeModulesLinker": "hoisted" }

nodeModulesDir applies only to projects without a package.json, so it is rarely the right knob.

Permissions

Deno grants no filesystem, network, environment, or subprocess access unless asked.

deno run --allow-net=api.example.com --allow-read=./data main.ts
deno run -A main.ts          # allow everything
FlagShortGrants
--allow-read[=paths]-Rfilesystem read
--allow-write[=paths]-Wfilesystem write
--allow-net[=hosts]-Nnetwork
--allow-env[=names]-Eenvironment variables
--allow-sys[=apis]-SOS information
--allow-import[=hosts]-Iimports from remote hosts
--allow-run[=bins]—subprocesses
--allow-ffi[=paths]—native libraries (unstable)
--allow-all-Aeverything

-S is --allow-sys, not --allow-run. Every flag takes an allowlist — --allow-net=example.com:443 beats bare --allow-net. Matching --deny-* flags always win.

On Requires net access to "...", add that specific permission. -A is fine for trusted first-party code and during migration, but a poor default to commit in a task.

Configuration

deno.json (or .jsonc) is auto-discovered from the current directory upward.

{
  "tasks": {
    "dev": "deno watch -A main.ts",
    "start": "deno run -A main.ts"
  },
  "fmt": { "exclude": ["build/"] },
  "lint": { "rules": { "exclude": ["no-explicit-any"] } },
  "exclude": ["build/", "dist/"]
}

Top-level exclude applies to every subcommand; per-tool exclude narrows it.

deno.json also accepts imports, an import map pointing bare specifiers at real ones. That is how a project without package.json declares dependencies, and how a JSR package declares its own alongside name, version, exports.

Workspaces

npm, Yarn, and Bun workspaces work out of the box — Deno reads package.json "workspaces" directly. pnpm is the exception: pnpm-workspace.yaml is migrated into deno.json on first run, which must then be re-run.

{ "workspace": ["./packages/core", "./packages/cli"] }

Members are explicit or single-level globs ("packages/*"); ** and negation are unsupported. Run a task across members with deno task --filter '*' build.

Packages: npm and JSR

Prefer npm — it is where the ecosystem is, and deno add express is the normal case. Reach for JSR for the standard library (@std/*), or to publish TypeScript that consumers get types for without a build step. Mixing is fine.

deno add jsr:@std/path npm:express
deno doc jsr:@std/path        # read a package's API from the terminal

Deno once used full URL imports (https://deno.land/x/...). They still run but aren't recommended; to modernize, deno add the package and import the bare specifier.

Built-in tooling

deno fmt              # format (--check for CI)
deno lint             # lint (--fix, --rules)
deno test             # tests (--watch, --parallel, --coverage=dir)
deno check main.ts    # type-check without running
deno bench            # benchmarks
deno coverage         # coverage report from --coverage output
deno compile main.ts  # single-file executable (--target cross-compiles)
deno doc mod.ts       # docs (--html for a site)
deno info main.ts     # module graph and cache info

These cover prettier, eslint, jest/vitest, tsc, and pkg/nexe with no config or dependencies — but they are not drop-in replacements. Parity is incomplete, so moving an established project is real work. There is no need to migrate: keep prettier, eslint, and vitest, and use Deno as runtime and package manager. Prefer the built-in tools for new projects.

Suppress with // deno-lint-ignore <rule>, // deno-lint-ignore-file, // deno-fmt-ignore, // deno-fmt-ignore-file. In Markdown, <!-- deno-fmt-ignore --> before a code block protects illustrative snippets that aren't valid standalone code.

Running code

deno main.ts                 # deno run is optional
deno watch main.ts           # reload on change (replaces nodemon)
deno task dev                # task from package.json or deno.json
deno repl
deno eval "console.log(1)"

deno watch hot-replaces modules, restarting if that fails; it aliases deno run --watch-hmr.

An HTTP server needs no dependencies:

Deno.serve((_req) => new Response("Hello"));

Starting a new project

Scaffold rather than hand-writing the files:

deno init my-project          # script + test + deno.json
deno init --empty my-project  # just main.ts and deno.json
deno init --lib my-lib        # library laid out for JSR
deno create vite my-app       # scaffold from a package initializer

deno create is npm create / yarn create and covers that ecosystem (deno create astro, etc). Unprefixed names are npm; --jsr selects JSR.

Publishing

To npm the regular flow still works — npm publish, or deno pack to build the tarball first. deno publish targets JSR only, from a deno.json with name, version, and exports:

deno publish --dry-run
deno publish

Provenance attestation is automatic on GitHub Actions. deno bump-version patch bumps the version, across every member at a workspace root.

Guide: https://docs.deno.com/runtime/reference/cli/publish/

Reviewing Deno code

  • -A committed in a task where a scoped grant would work.
  • deno.lock uncommitted, or CI running deno install instead of deno ci.
  • Inline jsr:/npm: specifiers in a project with a package.json — use deno add so the version lives in one place. Fine in standalone scripts.
  • A specifier with no version constraint.
  • Dependencies or compiler options in deno.json when package.json or tsconfig.json exists.
  • Missing deno fmt --check, deno lint, deno check in CI.

Further reading

  • https://docs.deno.com — runtime documentation
  • https://docs.deno.com/api/ — Deno.* API reference
  • references/CLI.md — fuller subcommand and flag reference
  • deno <subcommand> --help — authoritative and version-accurate; check it before guessing at a flag.

Migrating to Deno

Requires Deno 2.9 or later. For general Deno usage once migrated, see the deno skill.

Most Node projects already run under Deno

Deno reads an existing package.json, resolves the same npm packages, writes a real node_modules, runs the same scripts, and supports node: built-ins. TypeScript runs with no build step.

There is usually no code to change — only which binary you invoke. Don't start by rewriting imports to jsr:, swapping dependencies for Deno-specific ones, or restructuring directories. Proposing that is the most common way this goes wrong.

Migrate in rungs

Each rung is independently useful and reversible. Stop wherever suits the project; plenty of teams stop at rung 1.

Rung 1 — Deno as the package manager only

deno install

Reads package.json, resolves the same dependencies, writes node_modules, and creates deno.lock — seeded from any existing package-lock.json, yarn.lock, bun.lock, or pnpm lockfile, so pins and integrity hashes carry over instead of drifting.

The app still runs under node; teammates are unaffected. Commit deno.lock once verified. To back out: delete deno.lock and node_modules, then npm install.

Rung 2 — Run it with Deno

deno run -A main.js      # or: deno -A main.js
deno task build          # runs scripts.build from package.json

Use -A here. The goal is confirming the program works, not designing a permission policy — changing both at once makes failures ambiguous.

Rung 3 — Tighten permissions

Replace -A with the narrowest set that works: run it, read what it asks for, grant exactly that.

deno run --allow-net=api.example.com --allow-read=./config --allow-env=PORT main.js

This buys something Node cannot offer, and is worth doing before deploying.

Rung 4 — Optionally, adopt the built-in toolchain

deno fmt for prettier, deno lint for eslint, deno test for jest or vitest, deno check for tsc, deno watch for nodemon, deno compile for pkg.

Optional, and usually not worth it for an existing project. These are not drop-in replacements; parity is incomplete, so this is a real migration, not a config change. A project happy with prettier, eslint, and vitest should keep them and use Deno as runtime and package manager only. Prefer the built-in tools for new projects. If you do move an existing one, go a tool at a time.

Command equivalents

TasknpmYarnpnpmBunDeno
Install allnpm installyarn installpnpm installbun installdeno install
Addnpm i <p>yarn add <p>pnpm add <p>bun add <p>deno add <p>
Add devnpm i -D <p>yarn add -D <p>pnpm add -D <p>bun add -d <p>deno add -D <p>
Removenpm uninstall <p>yarn remove <p>pnpm remove <p>bun remove <p>deno remove <p>
CI installnpm ciyarn install --immutable†pnpm i --frozen-lockfilebun install --frozen-lockfiledeno ci
Run scriptnpm run <s>yarn <s>pnpm <s>bun run <s>deno task <s>
Run binarynpx <p>yarn dlx <p>pnpm dlx <p>bunx <p>dx <p>
Outdatednpm outdatedyarn outdated‡pnpm outdatedbun outdateddeno outdated
Auditnpm audityarn npm audit†pnpm auditbun auditdeno audit
Whynpm ls <p>yarn why <p>pnpm why <p>bun why <p>deno why <p>
Run a filenode f.jsbun f.tsdeno f.ts
Run TSts-node f.tsbun f.tsdeno f.ts
Watchnodemon f.jsbun --watch f.tsdeno watch f.ts
Formatprettierprettierdeno fmt
Linteslintdeno lint
Testjest, vitestbun testdeno test
Coveragenyc, c8deno coverage
Type-checktsc --noEmittscdeno check
Bundle binarypkg, nexebun build --compiledeno compile

† Yarn Berry (v2+) spelling. Yarn Classic (v1) uses yarn install --frozen-lockfile and yarn audit.

‡ Yarn Classic only — Berry removed yarn outdated.

dx is a separate binary installed alongside Deno, and an alias for deno x. It does not appear in the top-level deno --help output. Like npx, it runs the package with the sandbox disabled.

The four things that actually break

Requires net access to "..." (or read, env, run)

Deno grants nothing by default. Add that specific permission, or -A while still establishing the program works at all.

ReferenceError: require is not defined

A file containing CommonJS is being parsed as ESM. .cjs is always CommonJS, .mjs always ESM; .js and .ts follow "type" in the nearest package.json. For a CommonJS project, set "type": "commonjs".

A dependency is broken, or postinstall never ran

Lifecycle scripts don't run by default. Native addons notice immediately. Approvals are recorded in the config file, so this is one-time:

deno approve-scripts                              # interactive picker
deno install --allow-scripts=npm:better-sqlite3   # or name them directly

A tool cannot find files inside node_modules

Deno's layout is pnpm-style: real files in node_modules/.deno/, exposed via symlinks. Tools assuming npm's flat hoisted tree need:

{ "nodeModulesLinker": "hoisted" }

What has no Deno equivalent

Say so rather than improvising a workaround that won't hold:

  • Yarn Plug'n'Play. Deno creates a real node_modules; .pnp.cjs is unused and .yarnrc.yml resolver settings don't transfer.
  • yarn patch / pnpm patched dependencies. Vendor or fork.
  • overrides / resolutions. Pin via an import map entry instead.
  • Registry and resolver tuning in .npmrc / .yarnrc.yml.
  • Bun build features — macros, HTMLRewriter, HTML entrypoints.

Per-tool details

  • references/FROM_NPM.md — lockfile seeding, node_modules layout, overrides
  • references/FROM_YARN.md — Plug'n'Play, Berry vs Classic, workspaces
  • references/FROM_PNPM.md — pnpm-workspace.yaml, catalog:, patches
  • references/FROM_BUN.md — Bun API translation, bunfig.toml
  • references/NODE_APIS.md — node: built-ins, DENO_COMPAT, CJS/ESM

Further reading

Sponsors

Details

Marketplace
denoland/skills
Category
Community