deno

Files (14)

• SKILL.md
• SKILL.md · oak/
• deno-runtime-guide.md · oak/references/
• oak-middleware.md · oak/references/
• oak-performance.md · oak/references/
• oak-routing-deployment.md · oak/references/
• oak-setup.md · oak/references/
• oak-testing.md · oak/references/
• deno-advanced.md · references/
• deno-deployment.md · references/
• deno-essentials.md · references/
• deno-fundamentals.md · references/
• deno-runtime.md · references/
• fresh-framework.md · references/

SKILL.md (first lines)

# Deno

## Purpose
Build TypeScript services on Deno 2 with least-privilege permissions, JSR-first dependencies, built-in tooling (fmt, lint, test, check, compile) and a choice of bare `Deno.serve`, Hono, Oak or Fresh.

## Agent Protocol

### Trigger
Exact user phrases: "deno", "deno 2", "deno.json", "deno task", "deno compile", "deno test", "Deno.serve", "Deno KV", "JSR", "deno permissions", "Fresh framework".

### Input Context
- Deno version (assume 2.x) and deployment target (Deno Deploy, Docker, compiled binary).
- Framework (bare `Deno.serve`, Hono, Oak, Fresh).
- Data store (Deno KV, PostgreSQL via `npm:pg`/`jsr:@db/postgres`, Redis).
- Required permissions (net, read, write, env, run, ffi).

### Output Artifact
`deno.json`, server code, tests and run/deploy commands with explicit permissions. No files unless requested.

### Response Format
```
Deno: 2.x   Framework: {bare|Hono|Oak|Fresh}
Permissions: --allow-net={hosts} --allow-env={vars} --allow-read={paths}
Deps: {jsr:/npm: specifiers in deno.json imports}
Files: {deno.json, src/main.ts, tests}
Run: deno task {dev|start|test}
```

## Decisions

### Framework

| Need | Choice |
|---|---|
| Small API, no deps | `Deno.serve` + `URLPattern` |
| Typed REST API with middleware ecosystem, multi-runtime | Hono (`jsr:@hono/hono`) |
| Koa-style middleware, existing Oak codebase | Oak (`jsr:@oak/oak`) |
| Server-rendered pages with interactive islands | Fresh 2 (`jsr:@fresh/core`, built on Vite) |

### Dependencies
- Prefer **JSR** (`jsr:@std/...`, `jsr:@hono/hono`): semver, TypeScript source, provenance.
- Use **npm** (`npm:pkg@^x`) for packages that only exist there; Deno 2 supports `package.json` and `node_modules` when needed.
- Avoid `https://deno.land/std` and `deno.land/x` URLs in new code: the standard library now lives on JSR as `@std/*`.
- Declare everything in `deno.json` `imports`; `deno.lock` is created and checked automatically.

### Permissions
Grant the narrowest scope: `--allow-net=api.example.com:443,0.0.0.0:8000`, `--allow-env=DATABASE_URL,PORT`, `--allow-read=./static`. Avoid `-A` outside local scripts. Deno 2 also offers `--deny-*` flags to carve exceptions out of broader grants.

## Workflow

### Step 1: deno.json

```json
{
  "tasks": {
    "dev": "deno run --watch --allow-net --allow-env=PORT,DATABASE_URL src/main.ts",
    "start": "deno run --allow-net --allow-env=PORT,DATABASE_URL src/main.ts",
    "test": "deno test --allow-net --allow-env",
    "check": "deno check src/main.ts && deno lint && deno fmt --check",
    "compile": "deno compile --allow-net --allow-env=PORT,DATABASE_URL --output dist/api src/main.ts"
  },
  "imports": {
    "@hono/hono": "jsr:@hono/hono@^4",
    "@std/assert": "jsr:@std/assert@^1",
    "zod": "npm:zod@^3"
  },
  "compilerOptions": { "strict": true },
  "fmt": { "lineWidth": 100, "singleQuote": true }
}
```

### Step 2: Hono API on Deno.serve

```ts
// src/app.ts
import { Hono } from '@hono/hono';
import { cors } from '@hono/hono/cors';
import { logger } from '@hono/hono/logger';
import { HTTPException } from '@hono/hono/http-exception';
import { z } from 'zod';

const kv = await Deno.openKv(Deno.env.get('KV_PATH')); // undefined -> default local store

const UserInput = z.object({ name: z.string().min(2), email: z.string().email() });
type User = z.infer<typeof UserInput> & { id: string };

export const app = new Hono();
app.use('*', logger());
app.use('/api/*', cors({ origin: Deno.env.get('CORS_ORIGIN') ?? 'http://localhost:5173' }));

app.get('/health', (c) => c.json({ status: 'ok' }));

app.get('/api/v1/users', async (c) => {
  const users: User[] = [];
  for await (const entry of kv.list<User>({ prefix: ['users'] }, { limit: 100 })) {
    users.push(entry.value);
  }
  return c.json({ data: users });
});

app.post('/api/v1/users', async (c) => {
  const parsed = UserInput.safeParse(await c.req.json());
  if (!parsed.success) return c.json({ error: parsed.error.flatten() }, 400);
  const user: User = { id: crypto.randomUUID(), ...parsed.data };
  // atomic check prevents overwriting an existing key
  const res = await kv.atomic()
    .check({ key: ['users', user.id], versionstamp: null })
    .set(['users', user.id], user)
    .commit();
  if (!res.ok) throw new HTTPException(409, { message: 'user exists' });
  return c.json({ data: user }, 201);
});

app.get('/api/v1/users/:id', async (c) => {
  const { value } = await kv.get<User>(['users', c.req.param('id')]);
  return value ? c.json({ data: value }) : c.json({ error: 'not found' }, 404);
});

app.onError((err, c) => {

From j4flmao/agent-skills, MIT.

More from j4flmao/agent-skills