Run TypeScript Directly in Deno: A Practical Guide to Native Execution

Desired Outcome

Execute TypeScript files directly with deno run without a separate compilation step, while retaining type safety through optional static checking and respecting Deno's permission model.

Prerequisites

• Deno 1.0 or later installed (deno --version should report 1.0.0 or higher)
• Basic familiarity with TypeScript syntax and ES modules
• A terminal with permission to execute Deno commands

Procedure

1. Create a TypeScript Entry Point

Write a .ts file using standard ES module imports. Deno resolves dependencies from URLs or local paths without package.json or node_modules.

// hello.ts
export function greet(name: string): string {
  return `Hello, ${name}!`;
}

if (import.meta.main) {
  console.log(greet("Deno"));
}

2. Run the File Directly

Execute the script with deno run. Deno compiles TypeScript on-the-fly using its built-in compiler (based on swc).

deno run hello.ts

Expected output:

Hello, Deno!

3. Add Runtime Permissions

Deno's security model requires explicit flags for I/O, network, and environment access. TypeScript execution does not change this.

// read-file.ts
const decoder = new TextDecoder();
const data = await Deno.readFile("data.txt");
console.log(decoder.decode(data));

deno run --allow-read read-file.ts

Omitting --allow-read produces a PermissionDenied error at runtime, not compile time.

4. Enable Static Type Checking Before Execution

Use --check to run the type checker without executing code. This catches type errors early in CI or pre-commit hooks.

deno check hello.ts
# or
deno run --check hello.ts

deno check exits with a non-zero code if type errors exist. deno run --check type-checks then runs if clean.

5. Import External TypeScript Modules

Deno imports TypeScript directly from URLs. The compiler resolves and type-checks remote modules on first run, caching them locally.

// fetch-example.ts
import { parse } from "https://deno.land/std@0.224.0/flags/mod.ts";

const args = parse(Deno.args, { string: ["name"] });
console.log(greet(args.name ?? "world"));

deno run --allow-net fetch-example.ts --name=Reader

Expected Checks

Recovery Options

Type Errors at Runtime

If deno run fails with a type error (rare, since Deno checks before execution), fix the source and re-run. Use deno check first to isolate type issues from runtime logic.

Permission Denied

Add the minimal required flag: --allow-read, --allow-write, --allow-net, --allow-env, --allow-run. Avoid -A (allow all) in production.

Slow Startup on Large Projects

Runtime compilation adds latency proportional to module graph size. Mitigations:

• Use deno compile to produce a standalone binary for distribution
• Leverage Deno's cache: subsequent runs reuse compiled output unless sources change
• Split large entry points; Deno caches per-module

Cache Corruption

If imports behave unexpectedly, clear the compilation cache:

deno cache --reload fetch-example.ts

This forces re-fetch and re-compilation of all dependencies.

Limitations

• Startup overhead: First run compiles the full module graph. Cold starts are slower than pre-bundled JavaScript.
• No tsconfig.json required: Deno uses sensible defaults (strict mode, ESNext target). Custom compiler options are limited to compilerOptions in deno.json and only affect deno check/deno lint, not runtime compilation.
• Type-only imports: Use import type for types erased at runtime; Deno respects this but does not enforce it beyond standard TS behavior.

Verification Checklist

1. Confirm Deno version: deno --version ≥ 1.0.0
2. Run a minimal .ts file without tsc installed
3. Verify --check catches a deliberate type error
4. Confirm permission flags gate I/O independently of TypeScript
5. Compare deno run example.ts and deno run example.js for identical output