scriptc

Product Introduction

1. Definition: scriptc is a TypeScript-to-native compiler, a tool in the static compilation and developer tooling category. It transforms standard TypeScript source code into standalone, self-contained native executables for macOS, Linux, and Windows.
2. Core Value Proposition: It exists to eliminate the massive runtime dependencies and performance overhead of Node.js and JavaScript engines. scriptc delivers the developer productivity of TypeScript with the execution speed, small binary size, and system portability of natively compiled languages like Go or Rust.

Main Features

1. Explicit Three-Tier Compilation Model: scriptc categorizes every construct in a program into one of three tiers. Tier 1 is statically compiled to native machine code, covering most ordinary TypeScript, classes, async/await, and the Node.js standard library surface. Tier 2 runs dynamically within an embedded, minimal JavaScript engine (~620KB), which is only included when explicitly opted into via the --dynamic flag for handling npm package code or dynamic any types. Tier 3 consists of unsupported features that cause a compile-time error with specific diagnostics, preventing silent miscompilation.
2. Staticness Coverage Analysis: The scriptc coverage command provides a detailed, statement-by-statement report of a codebase. It shows the percentage of code that compiles statically, explicitly lists every site that requires the dynamic engine, and gives specific error codes (e.g., SC2013) and hints for incompatible constructs. This transparency ensures developers understand the composition of their final binary.
3. Zero-Code-Change Philosophy: scriptc uses the official TypeScript compiler for type checking and requires no code annotations, proprietary language dialects, or special standard libraries. Developers can compile existing Node.js-targeted TypeScript code without modification, maintaining full ecosystem compatibility for static portions.

Problems Solved

1. Pain Point: It directly addresses the "Node.js dependency bloat" problem, where deploying a simple TypeScript tool requires a ~120MB runtime environment. It also solves "slow startup times" inherent in JIT-based engines, which add tens of milliseconds of overhead for short-lived processes like CLIs or serverless functions.
2. Target Audience: The primary user personas are infrastructure engineers building internal developer tools, backend developers creating microservices or APIs, and open-source maintainers shipping cross-platform command-line interfaces (CLIs) who want the ergonomics of TypeScript but need the performance and clean deployment story of a native binary.
3. Use Cases: Essential scenarios include building fast-starting serverless functions (FaaS), creating single-file, dependency-free command-line tools for distribution, embedding logic into resource-constrained environments, and generating high-performance data processing utilities from TypeScript algorithms.

Unique Advantages

1. Differentiation: Unlike tools that bundle the entire Node.js runtime (e.g., pkg) or transpile to another language, scriptc performs genuine ahead-of-time (AOT) compilation to native code for the static tier. Compared to Deno or Bun, which are optimized JavaScript runtimes, scriptc aims to remove the runtime engine altogether where possible.
2. Key Innovation: Its core innovation is the principled, hybrid execution model with strict boundaries. The guarantee that "a binary never silently grows an engine" because the dynamic tier is an explicit, opt-in build flag provides unparalleled predictability and control over the final artifact's size and behavior.

Frequently Asked Questions (FAQ)

1. How does scriptc handle npm packages? npm packages that ship JavaScript source code cannot be statically compiled and must run in the explicit dynamic tier. Importing such a package triggers a coverage report warning and requires using the --dynamic flag, which embeds the minimal engine to execute that dependency.
2. Is scriptc a replacement for the TypeScript compiler (tsc)? No, scriptc is not a type checker. It uses the real TypeScript compiler internally for type checking and then performs the subsequent step of compilation to native executable binaries, a process tsc does not do.
3. What are the limitations of scriptc's static compilation? Dynamic code patterns like eval(), certain uses of Function constructor, and highly dynamic meta-programming are rejected at compile time (Tier 3). Features requiring a full Node.js environment, like VM modules or native addons, are not supported.
4. Can I use scriptc for frontend web development? No, scriptc is specifically designed for compiling TypeScript to native system executables, not for web browser targets. It is for backend, CLI, and server-side applications.
5. How does scriptc ensure correctness of the compiled output? scriptc employs differential testing: a corpus of test programs is executed both under standard Node.js and as the native binary produced by scriptc. Their output, errors, and exit codes must match byte-for-byte. Furthermore, the native binaries are tested with AddressSanitizer to detect memory corruption bugs.