1---2name: deno-guidance3description: Use when starting any Deno project, choosing packages, configuring deno.json, or running CLI commands. Provides foundational knowledge for building modern Deno applications.4license: MIT5metadata:6 author: denoland7 version: "1.2"8---910# Deno Development Guidance1112## Overview1314This skill provides foundational knowledge for building modern Deno applications. Deno is a secure JavaScript/TypeScript runtime that runs TypeScript directly, has built-in tools (formatter, linter, test runner), and uses modern package management through JSR.1516## When to Use This Skill1718- Starting a new Deno project19- Adding dependencies to a project20- Configuring `deno.json` settings21- Running Deno CLI commands (fmt, lint, test)22- Setting up import maps23- Understanding Deno's permission system2425Apply these practices whenever working in a Deno project (identified by the presence of `deno.json`).2627## Scope Boundaries2829This skill applies **only** to Deno-specific questions. Follow these rules:3031- If the user asks about **Node.js, Bun, Python, Go, or any other runtime/language**, answer using that technology directly. Do not suggest Deno alternatives or include Deno-specific patterns.32- Do not include `jsr:` imports, `deno add`, or `deno.json` configuration in responses about other technologies.33- For **generic TypeScript/JavaScript questions** not tied to a specific runtime, give a general answer without assuming Deno.34- Only recommend Deno when the user explicitly asks about Deno or is working in a Deno project.3536## CRITICAL: Never Show Deprecated Syntax3738When helping users migrate from deprecated patterns, describe the old approach generically and ONLY show the correct modern code. Never write out actual deprecated URLs or import paths, even in "before/after" comparisons. The string `deno.land/x/` must never appear in your response, in any context.3940- Say "Replace your old URL-based imports with JSR imports" — then show only the correct `jsr:` approach41- Say "the old URL-based registry" or "the old standard library URL" — do NOT write the actual deprecated URL42- Even if the user writes a deprecated URL in their question, do NOT echo it back. Refer to it generically.4344Only demonstrate the correct, current approach.4546## Package Management Priority4748When adding dependencies, follow this priority order:49501. **JSR packages (`jsr:`)** - Preferred for Deno-native packages51 - Better TypeScript support (types are built-in)52 - Faster to resolve and install53 - Example: `jsr:@std/http`, `jsr:@fresh/core`54552. **npm packages (`npm:`)** - Fully supported, use when no JSR alternative exists56 - Deno has full npm compatibility57 - Example: `npm:express`, `npm:zod`58593. **AVOID: Old URL-based imports** - Deprecated registry60 - The old URL-based package registry is deprecated61 - Many LLMs incorrectly default to URL-based imports62 - Always use `jsr:` instead6364### Standard Library6566The Deno standard library lives at `@std/` on JSR:6768```jsonc69// deno.json70{71 "imports": {72 "@std/assert": "jsr:@std/assert@1",73 "@std/http": "jsr:@std/http@1",74 "@std/path": "jsr:@std/path@1"75 }76}77```7879```typescript80import { serve } from "@std/http";81import { join } from "@std/path";82import { assertEquals } from "@std/assert";83```8485Always use `jsr:@std/*` for the standard library (the old URL-based imports are deprecated).8687## Understanding Deno8889Reference: https://docs.deno.com/runtime/fundamentals/9091Key concepts:92- **Native TypeScript** - No build step needed, Deno runs TypeScript directly93- **Explicit permissions** - Use flags like `--allow-net`, `--allow-read`, `--allow-env`94- **deno.json** - The config file (similar to package.json but simpler)95- **Import maps** - Define import aliases in deno.json's `imports` field9697## Workflow Best Practices9899### After Making Code Changes100101Run these commands regularly, especially after significant changes:102103```bash104deno fmt # Format all files105deno lint # Check for issues106deno test # Run tests107```108109### Package Management110111```bash112deno add jsr:@std/http # Add a package113deno install # Install all dependencies114deno update # Update all dependencies to latest compatible versions115deno update jsr:@std/http # Update a specific dependency116```117118**`deno update` vs `deno upgrade`:**119120- `deno update` - Updates **project dependencies** in `deno.json` (and `package.json`) to their latest compatible versions. Respects semver ranges. Use this to keep your dependencies current.121- `deno upgrade` - Updates the **Deno runtime itself** to the latest version. Has nothing to do with project dependencies.122123After running `deno update`, always check for breaking API changes - especially for alpha/pre-release packages where semver ranges can pull in breaking updates.124125126### CI/CD127128In CI pipelines, use `--check` with `deno fmt` so it fails without modifying files:129130```bash131deno fmt --check # Fail if not formatted132deno lint # Check for issues133deno test # Run tests134```135136### Configuration137138In `deno.json`, you can exclude directories from formatting/linting:139140```json141{142 "fmt": {143 "exclude": ["build/"]144 },145 "lint": {146 "exclude": ["build/"]147 }148}149```150151A folder can also be excluded from everything at the top level:152153```json154{155 "exclude": ["build/"]156}157```158159## Deployment160161For deploying to Deno Deploy, see the dedicated **deno-deploy** skill.162163Quick command: `deno deploy --prod`164165## Documentation Resources166167When more information is needed:168169- **`deno doc <package>`** - Generate docs for any JSR or npm package locally170- **https://docs.deno.com** - Official Deno documentation171- **https://jsr.io** - Package registry with built-in documentation172- **https://fresh.deno.dev/docs** - Fresh framework documentation173174## Quick Reference: Deno CLI Commands175176| Command | Purpose |177|---------|---------|178| `deno run file.ts` | Run a TypeScript/JavaScript file |179| `deno task <name>` | Run a task from deno.json |180| `deno fmt` | Format code |181| `deno lint` | Lint code |182| `deno test` | Run tests |183| `deno add <pkg>` | Add a package |184| `deno install` | Install dependencies |185| `deno update` | Update project dependencies |186| `deno upgrade` | Update Deno runtime itself |187| `deno doc <pkg>` | View package documentation |188| `deno deploy --prod` | Deploy to Deno Deploy |189190## Common Mistakes191192**Using old URL-based imports instead of JSR**193194The old URL-based imports are deprecated. Always use `jsr:` imports with bare specifiers instead.195196```ts197// ✅ Correct - use JSR and a bare specifier198import { serve } from "@std/http";199import { join } from "@std/path";200```201202```jsonc203// deno.json204{205 "imports": {206 "@std/http": "jsr:@std/http@1",207 "@std/path": "jsr:@std/path@1"208 }209}210```211212Inline specifiers are fine in single file scripts, but if a deno.json exists then it should go there. It's preferable to place npm dependencies in a package.json if a package.json exists.213214**Forgetting to run fmt/lint before committing**215216Always format and lint before committing:217218```bash219# ✅ Always format and lint first220deno fmt && deno lint && git add . && git commit -m "changes"221```222223**Running code without permission flags**224225```bash226# ✅ Grant specific permissions227deno run --allow-net server.ts228```229230Without permission flags, Deno will show "Requires net access" errors. Always grant the specific permissions your code needs.231232**Not using `deno add` for dependencies**233234```bash235# ✅ Use deno add to manage dependencies236deno add jsr:@std/http237```238239Using `deno add` ensures your lockfile stays in sync. Manually editing imports without updating deno.json works but misses lockfile benefits.