
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-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add denoland/skills.
Contents
Discovered from sourceSkills 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
--tunnelflag. - Do not include
deno deploycommands, 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.
deployctlis for Deno Deploy Classic (deprecated)deno deployis the modern, integrated command built into the Deno CLI- Requires Deno >= 2.4.2 - the
deno deploysubcommand 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:
-
Create the app with
--no-waitso 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 -
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> -
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):
| Flag | Purpose |
|---|---|
--allow-node-modules | Include node_modules directory in upload |
--no-wait | Skip 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
| Flag | Description |
|---|---|
--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:
| Flag | Description |
|---|---|
--owner <name> | GitHub repository owner |
--repo <name> | GitHub repository name |
Build Configuration Flags
| Flag | Description |
|---|---|
--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-config | Skip 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):
| Flag | Description |
|---|---|
--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):
| Flag | Description |
|---|---|
--static-dir <dir> | Directory to serve static files from (required) |
--single-page-app | Serve index.html for routes that don't match a file |
Other Flags
| Flag | Description |
|---|---|
--dry-run | Validate everything without actually creating the app |
--no-wait | Don't wait for the build to complete |
--allow-node-modules | Include 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:
| Context | Purpose |
|---|---|
| Production | Live traffic on your production URL |
| Development | Preview deployments and branch URLs |
| Build | Only 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:
| Variable | Description |
|---|---|
DENO_DEPLOY | Always 1 when running on Deno Deploy |
DENO_DEPLOYMENT_ID | Unique ID for the current deployment |
DENO_DEPLOY_ORG_ID | Your organization's ID |
DENO_DEPLOY_APP_ID | Your application's ID |
CI | Set 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_, orOTEL_
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
| Engine | Use Case |
|---|---|
| Deno KV | Key-value storage, simple data, counters, sessions |
| PostgreSQL | Relational 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:
- Ask you to authenticate with Deno Deploy (opens a browser)
- Ask you to select which app to connect the tunnel to
- 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
| Command | Purpose |
|---|---|
deno deploy --prod | Deploy to production (app must exist first) |
deno deploy | Preview 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-wait | Create app without waiting for build to complete |
deno deploy create ... --allow-node-modules | Create app including node_modules |
deno deploy env add <var> <value> | Add plain text environment variable |
deno deploy env add <var> <value> --secret | Add secret environment variable |
deno deploy env list | List 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 logs | View 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
- Authentication - Interactive and CI/CD authentication
- Databases - Database provisioning and connections
- Deno KV - Key-value storage API and examples
- Domains - Custom domains and SSL certificates
- Frameworks - Framework-specific deployment guides
- Organizations - Managing orgs and members
- Runtime - Lifecycle, cold starts, and limitations
- Troubleshooting - Common issues and solutions
Documentation
- Official docs: https://docs.deno.com/deploy/
- CLI reference: https://docs.deno.com/runtime/reference/cli/deploy/
- Databases: https://docs.deno.com/deploy/reference/databases/
- Deno KV: https://docs.deno.com/deploy/reference/deno_kv/
- Domains: https://docs.deno.com/deploy/reference/domains/
- Environment variables & contexts: https://docs.deno.com/deploy/reference/env_vars_and_contexts/
- Organizations: https://docs.deno.com/deploy/reference/organizations/
- Runtime: https://docs.deno.com/deploy/reference/runtime/
- Tunnel: https://docs.deno.com/deploy/reference/tunnel/
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"indeno.json; Next.js does. - Permissions apply to the dev server too — framework tasks generally want
-A. - Deploying: see the
deno-deployskill, 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:
- Islands ship JavaScript — keep them small, leave everything else in
components/. - Island props must be serializable. Functions cannot be passed.
- 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 depthreferences/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/sandboximports,Sandbox.create(), orsandbox.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 sandboxesChildProcess- Represents a running processClient- For managing Deploy resources (apps, volumes)
Quick Reference
| Task | Code |
|---|---|
| Create sandbox | await using sandbox = await Sandbox.create() |
| Run command | sandbox.spawn("cmd", { args: [...] }) |
| Get output | const output = await child.output() |
| Write file | await sandbox.fs.writeFile(path, content) |
| Read file | await sandbox.fs.readFile(path) |
| Kill process | await child.kill() |
| Check status | const 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 installreads an existingpackage.jsonand writes a realnode_modules.deno add expressinstalls from npm. Unprefixed names default to npm.deno task buildrunsscripts.buildfrompackage.jsonortasks.buildfromdeno.json. If both define it,deno.jsonwins.- Node built-ins work prefixed or not:
node:fsandfsboth resolve. deno main.jsruns a file.deno runis 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
| File | Holds |
|---|---|
package.json | dependencies, scripts |
tsconfig.json | TypeScript compiler options |
deno.json | Deno 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
| Flag | Short | Grants |
|---|---|---|
--allow-read[=paths] | -R | filesystem read |
--allow-write[=paths] | -W | filesystem write |
--allow-net[=hosts] | -N | network |
--allow-env[=names] | -E | environment variables |
--allow-sys[=apis] | -S | OS information |
--allow-import[=hosts] | -I | imports from remote hosts |
--allow-run[=bins] | — | subprocesses |
--allow-ffi[=paths] | — | native libraries (unstable) |
--allow-all | -A | everything |
-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
-Acommitted in a task where a scoped grant would work.deno.lockuncommitted, or CI runningdeno installinstead ofdeno ci.- Inline
jsr:/npm:specifiers in a project with apackage.json— usedeno addso the version lives in one place. Fine in standalone scripts. - A specifier with no version constraint.
- Dependencies or compiler options in
deno.jsonwhenpackage.jsonortsconfig.jsonexists. - Missing
deno fmt --check,deno lint,deno checkin CI.
Further reading
- https://docs.deno.com — runtime documentation
- https://docs.deno.com/api/ —
Deno.*API reference references/CLI.md— fuller subcommand and flag referencedeno <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
| Task | npm | Yarn | pnpm | Bun | Deno |
|---|---|---|---|---|---|
| Install all | npm install | yarn install | pnpm install | bun install | deno install |
| Add | npm i <p> | yarn add <p> | pnpm add <p> | bun add <p> | deno add <p> |
| Add dev | npm i -D <p> | yarn add -D <p> | pnpm add -D <p> | bun add -d <p> | deno add -D <p> |
| Remove | npm uninstall <p> | yarn remove <p> | pnpm remove <p> | bun remove <p> | deno remove <p> |
| CI install | npm ci | yarn install --immutable† | pnpm i --frozen-lockfile | bun install --frozen-lockfile | deno ci |
| Run script | npm run <s> | yarn <s> | pnpm <s> | bun run <s> | deno task <s> |
| Run binary | npx <p> | yarn dlx <p> | pnpm dlx <p> | bunx <p> | dx <p> |
| Outdated | npm outdated | yarn outdated‡ | pnpm outdated | bun outdated | deno outdated |
| Audit | npm audit | yarn npm audit† | pnpm audit | bun audit | deno audit |
| Why | npm ls <p> | yarn why <p> | pnpm why <p> | bun why <p> | deno why <p> |
| Run a file | node f.js | bun f.ts | deno f.ts | ||
| Run TS | ts-node f.ts | bun f.ts | deno f.ts | ||
| Watch | nodemon f.js | bun --watch f.ts | deno watch f.ts | ||
| Format | prettier | prettier | deno fmt | ||
| Lint | eslint | deno lint | |||
| Test | jest, vitest | bun test | deno test | ||
| Coverage | nyc, c8 | deno coverage | |||
| Type-check | tsc --noEmit | tsc | deno check | ||
| Bundle binary | pkg, nexe | bun build --compile | deno 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.cjsis unused and.yarnrc.ymlresolver 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_moduleslayout, overridesreferences/FROM_YARN.md— Plug'n'Play, Berry vs Classic, workspacesreferences/FROM_PNPM.md—pnpm-workspace.yaml,catalog:, patchesreferences/FROM_BUN.md— Bun API translation,bunfig.tomlreferences/NODE_APIS.md—node:built-ins,DENO_COMPAT, CJS/ESM
Further reading
- https://docs.deno.com/runtime/migrate/ — official migration guides
- https://docs.deno.com/runtime/fundamentals/node/ — Node and npm compatibility
- https://docs.deno.com/runtime/reference/node_apis/ — per-module Node API status
Sponsors
Details
- Marketplace
- denoland/skills
- Category
- Community