# @git.zone/tsdeno

A smart wrapper around `deno compile` that isolates `package.json` during compilation — preventing devDependencies from inflating your binary by hundreds of megabytes.

## Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://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/](https://code.foss.global/) account to submit Pull Requests directly.

## Install

```bash
# Global install (recommended for CLI usage)
npm install -g @git.zone/tsdeno

# Or as a project dev dependency
pnpm install --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 renames** `package.json` → `package.json.bak`
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. **Restores** `package.json` — guaranteed, even if compilation fails (try/finally)

With `package.json` hidden, Deno only resolves dependencies declared in `deno.json` via `npm:` specifiers — which are your actual runtime dependencies.

## Usage

### CLI — Passthrough Mode

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

```bash
# 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:

```bash
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 (npmextra.json)

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

```bash
tsdeno compile
```

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

```json
{
  "@git.zone/tsdeno": {
    "compileTargets": [
      {
        "name": "myapp-linux-x64",
        "entryPoint": "mod.ts",
        "outDir": "./dist",
        "target": "x86_64-unknown-linux-gnu",
        "permissions": ["--allow-all"],
        "noCheck": true
      },
      {
        "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`)                     |

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

### Programmatic API

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

```typescript
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 npmextra.json
await tsDeno.compileFromConfig();
```

The `TsDeno` class handles the full package.json isolation lifecycle automatically.

### CI/CD Integration

Example Gitea/GitHub Actions workflow:

```yaml
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: Install tsdeno
    run: npm install -g @git.zone/tsdeno

  - name: Compile binary
    run: 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 hiding `package.json` during compilation, Deno falls back to resolving **only** the `npm:` specifiers in your `deno.json`. These are your intentionally declared runtime dependencies. Combined with `--node-modules-dir=none` (which prevents Deno from creating/reading a local `node_modules`), the result is a clean binary with only what you actually import.

### 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
- **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](./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 hello@task.vc.

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.