• ⚡ tsforge
  • 📖 Table of Contents
  • 🎯 Why tsforge?
  • ✨ Features
  • 🎬 Demo
    • 2. Register in your shell
    • 3. Reload and verify
    • 4. Use from any project
  • 🧰 Commands
    • Core Type-Checking
    • Diagnostics & Profiling
    • Project References (Monorepos)
    • Environment & Health
    • npm v12 Security
    • MISC
  • ⚙️ Configuration
  • 🔬 How It Works
  • 📋 Requirements
  • 📜 License
  • 👤 Author

Every TypeScript developer runs the same command hundreds of times a day:

npx tsc --noEmit

And every time, it feels slower than it should. The reasons are well-documented but rarely addressed in one place:

tsforge wraps tsc and tsgo in ergonomic shell functions so you get speed, visibility, and consistency — from any project directory.

• 🔍 Auto-discovery — Walks up from $PWD to find node_modules/.bin/tsc or tsgo. Works from any subdirectory of any project.
• ⚡ TypeScript 7 ready — First-class support for tsgo, the native Go compiler (8–12x speedup on real codebases).
• 📊 Rich diagnostics — --diagnostics, --extendedDiagnostics, --generateTrace (Chrome/Perfetto), --explainFiles, and --showConfig.
• 🏗️ Monorepo support — tsc-build and tsc-build-force for project references with --verbose.
• 🩺 Health checks — tsc-optimize audits your tsconfig.json for incremental, skipLibCheck, isolatedDeclarations, and composite.
• 🧹 Cache management — tsc-clean removes stale .tsbuildinfo when results feel wrong.
• 🔒 npm v12 aware — npm-audit-scripts lists dependencies that request preinstall/install/postinstall scripts (blocked by default in npm v12).
• 🎨 TTY-aware colors — Auto-disables colors when output is piped, safe for CI logs.
• 🛡️ Double-source guard — Sourcing the script twice does not redefine functions.
• 📦 Zero dependencies — Pure Bash + grep + time. Nothing to install.

See it in action (generate the GIF locally):

git clone https://github.com/setuju/tsforge.git
cd tsforge
make demo        # requires vhs, ttyd, ffmpeg

What the demo shows:

💡 Tip: The GIF is generated from demo.tape using VHS. Every commit to tsforge.sh or demo.tape regenerates it automatically via the demo.yml workflow.

tsforge/
├── tsforge.sh                          # Main script
├── package.json                        # npm metadata (for tooling & CI)
├── README.md                           # Primary documentation
├── LICENSE.md                          # MIT License
├── CONTRIBUTING.md                     # Contribution guide
├── CODE_OF_CONDUCT.md                  # Community standards
├── CHANGELOG.md                        # Version history
├── SECURITY.md                         # Security policy
├── CODEOWNERS                          # Auto-review assignment
├── Makefile                            # Convenience commands
├── shell.nix                           # Nix reproducible shell
├── flake.nix                           # Nix flake (modern)
├── Dockerfile                          # Multi-stage container
├── .dockerignore
├── demo.tape                           # VHS demo script
├── .gitignore
├── .editorconfig
├── .shellcheckrc
├── docs/
│   ├── ARCHITECTURE.md                 # How it works internally
│   ├── COMMANDS.md                     # Extended command reference
│   ├── TSconfig.md                     # tsconfig optimization guide
│   └── TROUBLESHOOTING.md              # Common issues & fixes
└── .github/
    ├── FUNDING.yml
    ├── dependabot.yml
    ├── ISSUE_TEMPLATE/
    │   ├── bug_report.md
    │   ├── feature_request.md
    │   └── config.yml
    ├── PULL_REQUEST_TEMPLATE.md
    └── workflows/
        ├── shellcheck.yml              # Lint on every push
        ├── test.yml                    # Smoke tests (Bash + Docker + Nix)
        ├── demo.yml                    # Auto-regenerate demo.gif
        └── release.yml                 # Tag → GitHub Release

curl -fsSL https://raw.githubusercontent.com/setuju/tsforge/main/tsforge.sh -o ~/tsforge.sh
chmod +x ~/tsforge.sh

# For Bash
echo '[ -f "$HOME/tsforge.sh" ] && source "$HOME/tsforge.sh"' >> ~/.bashrc

# For Zsh
echo '[ -f "$HOME/tsforge.sh" ] && source "$HOME/tsforge.sh"' >> ~/.zshrc

source ~/.bashrc   # or source ~/.zshrc
tsforge-help       # or just: tsc-help

cd /path/to/any/typescript/project
tsc-where          # confirm environment
tsc-optimize       # audit tsconfig
tsc-fast           # type-check with timing

tsc-fast                  # type-check current project
tsc-fast --pretty false   # extra flags pass through to tsc
tsgo-fast                 # native Go compiler (if installed)

tsc-diagx                 # deep timing report
tsc-why tsc-explain.txt   # write explanation to file
tsc-trace tsc-trace-dir   # then open Perfetto

tsc-build                 # incremental monorepo build
tsc-build-force           # nuclear option

tsc-where                 # environment dump
tsc-optimize              # tsconfig health check
tsc-clean                 # clear incremental cache

npm-audit-scripts         # build your allowlist

tsforge is driven entirely by your existing tsconfig.json. The tsc-optimize command checks for these performance-critical flags:

{
  "compilerOptions": {
    // 50–90% faster rebuilds
    "incremental": true,

    // Skip .d.ts checking from node_modules
    "skipLibCheck": true,

    // Parallel .d.ts emit (TypeScript 5.5+)
    "isolatedDeclarations": true,

    // Required for project references
    "composite": true,

    // Keep build info inside node_modules (auto-ignored)
    "tsBuildInfoFile": "./node_modules/.cache/tsconfig.tsbuildinfo"
  }
}

Run tsc-optimize to see which flags are missing in your project.

tsforge is a set of pure Bash functions. There is no binary, no build step, and no runtime.

1. Binary discovery — _ts_find_local_bin walks upward from $PWD until it finds node_modules/.bin/tsc (or tsgo). This means it works from src/components/ just as well as from the project root.
2. tsconfig discovery — _ts_find_tsconfig does the same for tsconfig.json.
3. Command dispatch — Each public function (tsc-fast, tsc-diagx, etc.) is a thin wrapper that adds _ts_header, passes through all extra arguments, and optionally wraps in time.
4. Color management — Colors are only emitted when [ -t 1 ] is true. Piped output stays clean.

There is no magic. Read the script — it is heavily commented.

No macOS/Linux-specific binaries are used. Windows users can run tsforge under WSL, Git Bash, or MSYS2.

MIT — see LICENSE.md.

Jack

• GitHub: @setuju
• Website: saturumah.net

If tsforge saves you time, consider giving it a ⭐ on GitHub.