@git.zone/tsdeno

A smart wrapper around deno compile that temporarily removes devDependencies from package.json during compilation — preventing dev-only packages from inflating your binary by hundreds of megabytes.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Install

# One-off CLI usage
pnpm dlx @git.zone/tsdeno compile --help

# Project dev dependency
pnpm add --save-dev @git.zone/tsdeno

🔥 The Problem

When you run deno compile in a project that has a package.json, Deno resolves every dependency listed — including devDependencies. It does not distinguish between dependencies and devDependencies. This means build tools like:

• 📦 rspack (~110 MB of native binaries)
• 📦 rolldown (~40 MB of native binaries)
• 📦 esbuild (~11 MB)
• 📦 typescript (~23 MB)
• 📦 tswatch, tsbundle, and their entire transitive trees

...all get bundled into your compiled executable, even though they're never imported at runtime.

A real-world example: a Deno server binary went from 596 MB to 1022 MB — with 426 MB of pure dead weight from dev-only build tools.

The root cause: Deno reads package.json and resolves the full dependency graph into its global cache, then embeds everything when compiling. There is no --omit=dev flag, no config to skip devDependencies, and --node-modules-dir=none alone doesn't help if package.json is present.

✅ The Solution

tsdeno compile wraps deno compile with a simple but effective strategy:

1. Temporarily rewrites package.json without devDependencies
2. Adds --node-modules-dir=none automatically (uses Deno's global cache instead of local node_modules)
3. Runs deno compile with all your arguments passed through
4. Prunes marked self-extracting staging generations after successful --self-extracting compiles
5. Restores the original package.json content — guaranteed, even if compilation fails (try/finally)

With a runtime-only package.json, Deno can resolve normal package dependencies without pulling in dev-only build and test tooling.

Usage

Reproducible runtime dependency locks

Generate the dependency lock with the same temporary runtime-only manifest that compilation uses. Deno's --prod can exclude development packages while retaining their workspace metadata in the lock; that metadata conflicts with a frozen compile under the sanitized manifest. tsdeno install owns the same manifest lock, interrupted-run recovery and exact restoration as tsdeno compile.

tsdeno install --entrypoint --lockfile-only --frozen=false --lock=deno.lock mod.ts
tsdeno compile --allow-all --frozen --lock=deno.lock --output dist/myapp mod.ts

Install flags pass through to deno install; --node-modules-dir=none is added unless explicitly supplied. The programmatic equivalent is await new TsDeno().install([...args]). A failed install restores the original manifest before propagating Deno's exit code. Review and commit the generated lock; ordinary builds should use --frozen.

CLI — Passthrough Mode

Drop-in replacement — just swap deno compile for tsdeno compile:

# Before (bloated binary):
deno compile --allow-all --no-check --output myapp mod.ts

# After (lean binary):
tsdeno compile --allow-all --no-check --output myapp mod.ts

All deno compile flags are passed through untouched. Cross-compilation works the same way:

tsdeno compile --allow-all --no-check \
  --output dist/myapp-linux-x64 \
  --target x86_64-unknown-linux-gnu \
  mod.ts

tsdeno compile --allow-all --no-check \
  --output dist/myapp-macos-arm64 \
  --target aarch64-apple-darwin \
  mod.ts

CLI — Config Mode (.smartconfig.json)

For projects with multiple compile targets, define them in .smartconfig.json instead of writing long CLI commands. Just run tsdeno compile with no arguments:

tsdeno compile

tsdeno reads compile targets from the @git.zone/tsdeno key in your .smartconfig.json:

{
  "@git.zone/tsdeno": {
    "keepStaging": false,
    "compileTargets": [
      {
        "name": "myapp-linux-x64",
        "entryPoint": "mod.ts",
        "outDir": "./dist",
        "target": "x86_64-unknown-linux-gnu",
        "permissions": ["--allow-all"],
        "noCheck": true,
        "selfExtracting": true,
        "keepStaging": false,
        "v8Flags": ["--max-old-space-size=512"]
      },
      {
        "name": "myapp-macos-arm64",
        "entryPoint": "mod.ts",
        "outDir": "./dist",
        "target": "aarch64-apple-darwin",
        "permissions": ["--allow-all"],
        "noCheck": true
      }
    ]
  }
}

Each compile target supports these fields:

| Field | Type | Required | Description | | -------------- | ---------- | -------- | ----------------------------------------------------- | | name | string | ✅ | Output binary name (combined with outDir for path) | | entryPoint | string | ✅ | Path to the entry TypeScript file | | outDir | string | ✅ | Directory for the compiled output | | target | string | ✅ | Deno compile target triple (e.g. x86_64-unknown-linux-gnu) | | permissions | string[] | ❌ | Deno permission flags (e.g. ["--allow-all"]) | | noCheck | boolean | ❌ | Skip type checking (--no-check) | | selfExtracting | boolean | ❌ | Extract embedded files to disk at runtime (--self-extracting) | | keepStaging | boolean | ❌ | Keep Deno self-extracting staging directories for debugging | | v8Flags | string[] | ❌ | V8 flags baked into the binary (e.g. ["--max-old-space-size=512"]). Compiled Deno binaries ignore NODE_OPTIONS/DENO_V8_FLAGS at runtime, so compile-time flags are the only way to apply V8 settings such as heap limits |

In config mode, package.json is sanitized once for the entire batch — all targets compile in sequence with a single sanitize/restore cycle.

Top-level keepStaging: true keeps staging for every target. Target-level keepStaging overrides it for a single compile target. You can also set TSDENO_KEEP_STAGING=true for one-off debugging.

Programmatic API

You can also use tsdeno as a library in your build scripts:

import { TsDeno } from '@git.zone/tsdeno';

const tsDeno = new TsDeno(); // uses process.cwd()
// or: new TsDeno('/path/to/project')

// Passthrough mode — pass args directly
await tsDeno.compile([
  '--allow-all',
  '--no-check',
  '--output', 'dist/myapp',
  '--target', 'x86_64-unknown-linux-gnu',
  'mod.ts',
]);

// Config mode — reads compile targets from .smartconfig.json
await tsDeno.compileFromConfig();

The TsDeno class handles the full package.json sanitize/restore lifecycle automatically.

CI/CD Integration

Example Gitea/GitHub Actions workflow:

steps:
  - name: Set up Deno
    uses: denoland/setup-deno@v1
    with:
      deno-version: v2.x

  - name: Set up Node.js
    uses: actions/setup-node@v4
    with:
      node-version: '22'

  - name: Enable pnpm
    run: corepack enable pnpm

  - name: Compile binary
    run: pnpm dlx @git.zone/tsdeno compile --allow-all --no-check --output myapp mod.ts

🧠 How It Works — Deep Dive

Why package.json Causes Bloat

Deno projects often have both deno.json (with npm: import specifiers for runtime deps) and a package.json (for npm publishing, scripts like tswatch/tsbundle, etc.). When deno compile runs:

1. Deno discovers package.json and resolves all listed packages (deps + devDeps)
2. These get cached in Deno's global npm cache
3. deno compile embeds everything it resolved — the full transitive closure
4. Your binary now contains build tools, linters, test frameworks, etc.

What tsdeno Does Differently

By rewriting package.json without devDependencies during compilation, Deno sees only runtime dependency sections while still being able to resolve normal package imports. Combined with --node-modules-dir=none (which prevents Deno from creating/reading a local node_modules), the result is a clean binary without dev-only tooling.

For deno compile --self-extracting, Deno can leave hidden staging generations next to the output binary, for example dist/.myapp/<hash>/.deno_compile_node_modules. tsdeno marks the expected sidecar root with .gitzone-tool-cache.json and removes marked staging generations after a successful compile once the final binary exists and is non-empty. Existing unmarked non-empty sidecar roots are not claimed or deleted.

Safety Guarantees

• Atomic restore: package.json is restored in a finally block — it will be put back even if deno compile crashes
• No-op when absent: If there's no package.json, tsdeno runs deno compile normally
• Exit code passthrough: If deno compile fails, tsdeno exits with the same code
• Marker-gated staging cleanup: Self-extracting staging cleanup only removes directories under a tsdeno-marked sidecar root
• Transparent: All output from deno compile is streamed through to your terminal

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

Company Information

Task Venture Capital GmbH Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at [email protected].

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.