Related Pages

Related topics: Frontend and Lowering: TypeScript to Typed IR, Backend Emitters and C Runtime, CLI, Operations, Escape Hatches, and Platforms

Introduction and Three-Tier Compilation Model

Overview and Purpose

scriptc is a compiler that takes TypeScript source code and produces standalone native executables. Unlike a traditional transpiler that emits JavaScript or a bytecode runtime, scriptc lowers a TypeScript program all the way down to machine code, so the output binary has no runtime dependency on Node.js, Deno, Bun, or V8. Source: README.md:1-40

The compiler is organised as a workspace of focused packages rather than a single monolithic binary. The CLI package drives the build, the compiler package owns the front-to-back pipeline, and a small tsc-based workspace handles the build itself. Source: packages/compiler/src/index.ts:1-60

The promise of the project is captured in the landing page headline: write TypeScript, ship a native binary. Source: docs/src/app/page.tsx:1-80

The Three-Tier Compilation Model

Compilation in scriptc is split into three cleanly separated tiers. Each tier has a single responsibility, an isolated directory inside packages/, and a public surface that the next tier consumes. Source: docs/src/app/how-it-works/page.mdx:1-60

flowchart LR
  A[TypeScript Source] --> B[Tier 1: Frontend]
  B --> C[Tier 2: IR / Lowering]
  C --> D[Tier 3: Native Codegen]
  D --> E[Native Executable]

Tier 1 — TypeScript Frontend

The first tier reuses the TypeScript compiler itself to parse, bind, and type-check the input program. Rather than reinvent a type system, scriptc shells out to tsc's createProgram API and walks the resulting TypeChecker output to obtain a fully type-resolved AST. Source: packages/compiler/src/index.ts:60-140

This is the same machinery that powers IDEs, which is why scriptc accepts a tsconfig.json and understands the same project references and path aliases a developer would expect. The type information collected at this stage is consumed by the next tier to drive accurate lowering. Source: docs/src/app/how-it-works/page.mdx:60-120

Tier 2 — Intermediate Representation and Lowering

The second tier walks the typed AST and lowers it into a language-agnostic intermediate representation. At this stage, TypeScript-specific constructs (e.g. generics, structural types, as casts) are erased, control-flow is normalised, and each top-level statement is mapped to a primitive IR construct. Source: packages/compiler/src/index.ts:140-240

The IR is intentionally close to LLVM IR so that the backend tier can be implemented as a relatively direct emitter rather than as a full optimiser. Keeping the IR minimal also makes it cheap to add new front-ends in the future — a direction raised by community members asking about JavaScript support in issue #13. Source: docs/src/app/introduction/page.mdx:1-60

Tier 3 — Native Code Generation

The third tier takes the IR and produces an executable. Generation is delegated to clang from an LLVM toolchain, which links against the standard runtime and emits a host-target binary by default. Cross-target builds (for example Windows .exe from a POSIX host) are supported by passing an explicit target triple. Source: packages/compiler/src/index.ts:240-340

Windows-specific behaviour — slash-normalised paths, the required .exe suffix, and shell-quoting of the workspace build command — lives in this tier and is what was fixed in v0.0.17 to make scriptc run work on Windows 10/11 without WSL. Source: README.md:40-120

CLI Entry Point and Lifecycle

The user-facing binary is scriptc. Its two most important subcommands are scriptc build, which produces a native executable from one or more entry files, and scriptc run, which builds and immediately executes the resulting program in a single invocation. Source: README.md:60-160

Under the hood, scriptc run performs three steps: it resolves the project using TypeScript's virtual filesystem, runs the full three-tier pipeline, and then execs the freshly built binary — replacing the current process on POSIX or invoking it through a shell on Windows. Source: docs/src/app/how-it-works/page.mdx:120-200

Current Limitations and Roadmap

The project is published as 0.0.x and is explicitly pre-stable. The native runtime currently covers the TypeScript subset used by the included examples; language features outside that subset may lower to runtime stubs rather than compiled code. Source: docs/src/app/introduction/page.mdx:60-140

Two open community threads map directly onto the tiers. Issue #10 reports that scriptc run fails on Windows because the TypeScript virtual filesystem does not see slash-normalised paths; the fix landed in v0.0.17 by normalising paths in the frontend before they reach createProgram. Issue #13 requests broader JavaScript support, which would require a parallel or shared IR lowering path in Tier 2 since JavaScript lacks the static type information that Tier 1 currently relies on. Source: README.md:40-120

Related Pages

Related topics: Introduction and Three-Tier Compilation Model, Backend Emitters and C Runtime

Frontend and Lowering: TypeScript to Typed IR

Purpose and Scope

The frontend package is the entry point of the scriptc compiler pipeline. It consumes a TypeScript source program, runs the TypeScript compiler API against it, and produces a fully typed intermediate representation (IR) that the rest of the compiler — codegen, optimization, and backend emission — consumes. The frontend is intentionally the only layer that depends on the TypeScript compiler API; everything downstream is expressed in terms of the scriptc IR so the project can swap in alternative frontends (for example, a future JavaScript / ECMAScript frontend as discussed in issue #13) without rewriting the backend.

Two distinct concerns live under packages/compiler/src/frontend:

1. A frontend-agnostic façade that exposes the typed IR (in program.ts and types.ts).
2. A concrete TypeScript 7–based implementation under ts7/ that adapts the TypeScript compiler API to that façade.

The "lowering" half of the topic is the act of converting TypeScript's checker-resolved AST, types, and symbols into scriptc's own IR nodes — a representation that retains type information but is no longer bound to TypeScript's internal data structures.

Source: packages/compiler/src/frontend/program.ts Source: packages/compiler/src/frontend/types.ts Source: packages/compiler/src/frontend/ts7/program.ts

High-Level Workflow

The frontend pipeline is a linear transformation:

1. Program creation — the ts7 program module wires up a TypeScript System (virtual filesystem), configures compiler options, and calls createProgram to parse and resolve the user's source files.
2. AST capture — the scriptc AST is built by walking the TypeScript AST and producing IR nodes that mirror the structural shape of the source while stripping away TypeScript-internal markers.
3. Type resolution — the checker module invokes the TypeScript type checker, then folds each node's resolved type into the IR, producing a typed IR where every binding carries a scriptc type descriptor.
4. Adapter export — the adapter module re-exports the typed IR through the frontend-agnostic façade so downstream packages (ir, codegen, runtime) can consume it without importing TypeScript.

The split between the ts7 implementation and the generic façade is deliberate: it isolates the dependency on the TypeScript compiler API to a single directory, making the rest of the compiler independent of the parser choice.

Source: packages/compiler/src/frontend/ts7/program.ts Source: packages/compiler/src/frontend/ts7/adapter.ts Source: packages/compiler/src/frontend/ts7/ast.ts Source: packages/compiler/src/frontend/ts7/checker.ts

ts7 Frontend Implementation

Program construction

ts7/program.ts is responsible for turning a user-supplied source path into a ts.Program. It constructs a ts.System backed by the scriptc virtual filesystem so that createProgram resolves imports and tsconfig.json files consistently across platforms. This is the layer that the v0.0.17 release notes call out for Windows fixes: the virtual filesystem now normalizes path separators before the TypeScript program sees them, and default executable names carry the .exe suffix that createProgram expects on Windows. Without this normalization, Windows users hit the "ts7 createProgram: project failed to open" error reported in issue #10.

Source: packages/compiler/src/frontend/ts7/program.ts

AST module

ts7/ast.ts walks the TypeScript AST and produces scriptc IR nodes. The output is a structurally faithful copy of the source — declarations, expressions, statements, and modifiers — but expressed in the IR's own node types rather than ts.Node subclasses. This module is the lowest layer of the lowering: it is purely structural and does not yet attach type information.

Source: packages/compiler/src/frontend/ts7/ast.ts

Checker module

ts7/checker.ts is where type information is folded into the AST. It asks the TypeScript checker for the resolved type of each binding and expression, then maps those ts.Type instances into the scriptc type system defined in frontend/types.ts. The result is a typed IR where every node carries a scriptcType descriptor suitable for downstream code generation. Because the checker relies on the TypeScript API for inference, this is also the layer most affected by upstream changes in TypeScript's checker — and the reason the project is pinned to a specific compiler version.

Source: packages/compiler/src/frontend/ts7/checker.ts Source: packages/compiler/src/frontend/types.ts

Adapter

ts7/adapter.ts is the boundary between the TypeScript-specific implementation and the rest of the compiler. It exports the typed IR through the generic frontend façade (re-exported from frontend/program.ts) and is the only module that downstream packages are expected to import indirectly. Keeping this boundary explicit is what makes the JavaScript frontend discussed in issue #13 plausible — a future ts7/js (or similarly named) directory could implement the same adapter contract without types being re-inferred from scratch.

Source: packages/compiler/src/frontend/ts7/adapter.ts Source: packages/compiler/src/frontend/program.ts

Typed IR and Frontend Façade

frontend/types.ts defines the scriptc type model that the checker emits into the IR. It is deliberately narrower than the TypeScript type system: it captures the subset that scriptc can faithfully lower to native code (primitives, references, functions, structs, tuples, unions as tagged variants, and so on). Types that fall outside this subset lower to runtime checks or are rejected with a diagnostic.

frontend/program.ts exposes the compiled Program value to the rest of the compiler. It is the public entry point that the CLI's scriptc run command invokes; it in turn delegates to the ts7 adapter. Centralizing this in one file means that swapping the parser, adjusting diagnostics, or adding new top-level compiler options does not require touching the CLI.

Source: packages/compiler/src/frontend/types.ts Source: packages/compiler/src/frontend/program.ts

Architecture Summary

Source: packages/compiler/src/frontend/program.ts Source: packages/compiler/src/frontend/types.ts Source: packages/compiler/src/frontend/ts7/program.ts Source: packages/compiler/src/frontend/ts7/adapter.ts Source: packages/compiler/src/frontend/ts7/ast.ts Source: packages/compiler/src/frontend/ts7/checker.ts

Community-Relevant Notes

• Windows path handling (issue #10, fix in v0.0.17): the virtual filesystem layer in ts7/program.ts had to normalize path separators before createProgram could resolve the project. This is the most user-visible frontend bug to date and is pinned by a Windows CI lane.
• JavaScript support (issue #13): the author of JS² notes that scriptc is TypeScript-only today. The frontend/adapter split is designed so a JavaScript frontend could reuse the IR and backend by providing a new ts7 (or js) directory that implements the same adapter contract — the structural placeholders are already there.

Related Pages

Related topics: Frontend and Lowering: TypeScript to Typed IR, CLI, Operations, Escape Hatches, and Platforms

Backend Emitters and C Runtime

The backend is the final stage of the scriptc compilation pipeline. After the frontend has produced a typed intermediate representation (IR) from a TypeScript program, the backend emitters translate that IR into C source code, prepend a runtime header, and write a self-contained .c file that can be compiled with clang into a native executable. The accompanying C runtime supplies the language primitives that TypeScript assumes but C does not natively provide: object allocation, property access, console output, and async/await scheduling.

Pipeline Position and Entry Point

The top-level compileCC function lives in packages/compiler/src/backend/cc.ts. It receives the compiled TypeScript IR along with metadata describing the target program, and orchestrates the rest of the backend steps. It instantiates an Emitter, feeds it the IR, then writes the resulting C text to disk and invokes clang to produce a native binary. The execution flow looks roughly like this:

The Emitter Class

packages/compiler/src/backend/emission/emitter.ts defines the Emitter class, which is the single object passed through every emission helper. It holds:

• A buffer (TextWriter) accumulating C source as the traversal proceeds.
• The current target triple and runtime version, which decide whether Windows-style executable suffixes or path separators are used (relevant to issue #10's Windows fix in v0.0.17).
• A symbol table mapping IR identifiers to C identifiers.
• Helper methods such as temp(), label(), and emit() that other emitters call.

Every other emission file — emit-exprs, emit-stmts, emit-async, emit-island — exports functions that take the Emitter plus a typed IR node and append C source to the buffer. This keeps individual emitters small and focused on a single syntactic category while sharing the same output stream. Source: packages/compiler/src/backend/emission/emitter.ts:1-80

Statement and Expression Emission

emit-stmts.ts is responsible for control flow: if/else, while, for, for...of, for...in, switch, try/catch, return, throw, and function/arrow declarations. Each TS construct is lowered to a C equivalent. Closures are lowered to structs that capture their free variables; loops are emitted using C99 for syntax; labelled break/continue is lowered to C goto. Source: packages/compiler/src/backend/emission/emit-stmts.ts:1-60

emit-exprs.ts handles the value world: binary and unary operators, calls, member access, literals, template strings, array/object literals, and the implicit conversions between TypeScript's boxed types (number, string, boolean, null, undefined) and C primitives. Property access on dynamic objects is lowered to runtime calls (for example sc_get(obj, key)); arithmetic on bigint is routed through dedicated runtime helpers so that it does not collide with the platform long long. Source: packages/compiler/src/backend/emission/emit-exprs.ts:1-80

Async, Promises, and the Runtime

emit-async.ts is the most interesting file from a runtime perspective. TypeScript's async/await model has no direct C analog, so the emitter transforms each async function into a state-machine function: every await becomes a switch case on a state variable, and the body is rewritten into a loop that resumes when the awaited promise settles. Each await is also a potential suspension point for the runtime scheduler, which multiplexes many such state machines on top of a small thread pool. Source: packages/compiler/src/backend/emission/emit-async.ts:1-80

The supporting runtime lives in packages/compiler/src/backend/c/ (adjacent to the emission files) and is concatenated in front of the emitted code by cc.ts. It exposes the C functions that the emitters call:

• Object allocation and a stop-and-copy garbage collector (sc_alloc, sc_collect).
• Property tables and dynamic dispatch (sc_get, sc_set, sc_call).
• A console_log family used by the console global.
• Promise primitives used by emit-async (sc_promise_new, sc_promise_then, sc_await).

Because the runtime is a single C snippet prepended to user code, the final binary is fully self-contained — no shared library, no installed package. This is also why Windows support in v0.0.17 had to ensure both the runtime headers and the produced executable respected .exe suffixes and forward-slash paths: the entire toolchain assumes a single, portable textual artifact.

Islands and Native Escape Hatches

emit-island.ts handles "islands" — literal C source that the author embeds directly in a TypeScript file via the /*-*/ comment syntax. Islands allow escape-hatch access to the C runtime and to libc without leaving the scriptc toolchain, and they are how the standard library (in packages/compiler/src/stdlib/) bridges to native I/O, networking, and other POSIX facilities. The emitter copies the island text verbatim into the output buffer, surrounded by helpers that allocate identifiers unique to the surrounding scope. Source: packages/compiler/src/backend/emission/emit-island.ts:1-40

Summary

The backend emitters form a coordinated set: emitter.ts owns the shared context, emit-stmts.ts and emit-exprs.ts lower the bulk of TypeScript syntax, emit-async.ts translates the async model into a runtime-scheduled state machine, and emit-island.ts preserves user-supplied native code. Together with the prepended C runtime, they turn a TypeScript program into a single C file that clang can compile directly into a native executable on Linux, macOS, and (since v0.0.17) Windows.

Related Pages

Related topics: Introduction and Three-Tier Compilation Model, Frontend and Lowering: TypeScript to Typed IR, Backend Emitters and C Runtime

CLI, Operations, Escape Hatches, and Platforms

The scriptc toolchain is delivered as a Node.js CLI fronted by the compiler package. This page covers the four interlocking concerns that govern how a developer interacts with scriptc from a shell: the CLI entry point, the path/operations layer that bridges shells and the TypeScript virtual filesystem, the FFI profile that selects a target platform, and the escape hatches (sidecars and the surface manifest) that let advanced users escape the generated runtime.

CLI Entry Point and Subcommands

The CLI is bootstrapped from packages/cli/src/main.ts, which acts as the dispatcher for top-level subcommands such as scriptc run, scriptc build, and the workspace orchestration commands documented in the release notes. Source: packages/cli/src/main.ts.

The entry point resolves the project's TypeScript program through ts.createProgram, which is why Windows shells historically failed with ts7 createProgram: project failed to open when paths were not normalized (issue #10). The CLI delegates slash normalization to the operations layer rather than relying on the host shell, keeping the program construction deterministic across PowerShell, Git Bash (MINGW64), and POSIX shells.

Path Operations and Cross-Platform Behavior

All filesystem operations used during compilation are funneled through packages/cli/src/paths.ts. This module normalizes absolute and relative paths to forward slashes before they enter TypeScript's virtual filesystem, applies the .exe suffix when constructing default executable names for any Windows build (native or cross-target), and rewrites shell-quoted arguments so the workspace build command survives Windows quoting semantics. Source: packages/cli/src/paths.ts.

These fixes are explicitly enumerated in the v0.0.17 changelog: "TypeScript's virtual filesystem now sees consistently slash-normalized Windows paths, default executable names carry the required .exe suffix for both native and cross-target Windows builds, and the workspace build command survives Windows shell quoting." The CI lane added in the same release pins these regressions so future Windows breakage fails fast rather than slipping into a published CLI build. Source: packages/compiler/src/paths.ts (call-out referenced in release notes).

The diagram below shows the path flow from shell invocation to the compiler's filesystem view.

flowchart LR
  Shell[Shell - PowerShell / bash / zsh] --> CLI[main.ts dispatcher]
  CLI --> Paths[paths.ts normalize]
  Paths --> VFS[TypeScript virtual FS - forward slashes]
  VFS --> Program[ts.createProgram]
  Program --> Codegen[IR / codegen]
  Codegen --> Exe[Native executable .exe on Windows]

FFI Profiles and Platform Targeting

The compiler selects how to lower foreign-function interface calls through packages/compiler/src/ffi/profile.ts. A profile is a named bundle of calling-convention metadata, library search rules, and type-marshalling directives keyed to a target triple (for example x86_64-pc-windows-msvc, aarch64-apple-darwin, or wasm32-wasi). The CLI passes the resolved profile to the codegen pipeline so that imported symbols from a C/C++ sidecar resolve against the correct ABI. Source: packages/compiler/src/ffi/profile.ts.

Because Windows ships multiple C runtimes (MSVC vs. MinGW), the profile module also resolves the toolchain binary (clang, link, lib) and propagates any required .lib import library references. The CLI relies on this profile to decide whether to emit a .exe artifact or an undecorated ELF/Mach-O binary, aligning with the path-suffix logic in paths.ts. Source: packages/compiler/src/ffi/profile.ts.

Escape Hatches: Sidecars and the Surface Manifest

When a generated program must interoperate with a hand-written native library, scriptc offers two escape hatches that bypass the normal IR lowering.

The first is the sidecar mechanism in packages/compiler/src/library/sidecar.ts. A sidecar is an external library (typically a .so, .dylib, .dll, or .exe plus headers) that the generated binary loads at runtime. The module loads the declared sidecar, resolves its exported symbols against the FFI profile, and arranges for the appropriate loader path on the target platform. Source: packages/compiler/src/library/sidecar.ts.

The second layer is validation through packages/compiler/src/library/sidecar-validate.ts, which runs before code generation and checks that the requested symbols, argument types, and calling conventions match the sidecar's actual ABI. Mismatches surface as compile-time errors rather than runtime crashes, giving users a deterministic failure path. Source: packages/compiler/src/library/sidecar-validate.ts.

The third escape hatch is the surface manifest, declared at packages/compiler/surface-manifest.json. This file enumerates the compiler's externally observable surface (public IR nodes, supported FFI types, CLI flags, and version metadata). Tooling authors and integrators consult this manifest to detect breaking changes and to drive code generation in downstream clients. Source: packages/compiler/surface-manifest.json.

Related Community Signals

The Windows fix in v0.0.17 directly addresses issue #10, where native Windows shells could not run scriptc run because ts.createProgram rejected mixed-slash paths. A separate request, issue #13, asks for JavaScript/ECMAScript support; this sits at the boundary of the escape hatches because adding a JS IR layer would require entries in the surface manifest and likely a new FFI profile for JS runtimes. Neither request changes the CLI dispatch model described here, but both extend it.

Summary

• main.ts is the single CLI entry point and selects subcommands.
• paths.ts normalizes paths so the TypeScript virtual FS behaves identically on Windows and POSIX.
• ffi/profile.ts selects ABI, toolchain, and executable-suffix rules per target.
• sidecar.ts, sidecar-validate.ts, and surface-manifest.json provide the documented escape hatches for native interop and downstream tooling.

Together, these modules turn the CLI into a portable operations layer with predictable failure modes and well-marked extension points.

Doramagic Pitfall Log

Found 9 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/vercel-labs/scriptc/issues/3

2. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/vercel-labs/scriptc/issues/10

3. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://news.ycombinator.com/item?id=49063175

4. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://news.ycombinator.com/item?id=49063175

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://news.ycombinator.com/item?id=49063175

6. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://news.ycombinator.com/item?id=49063175

7. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/vercel-labs/scriptc/issues/13

8. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://news.ycombinator.com/item?id=49063175

9. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://news.ycombinator.com/item?id=49063175

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using scriptc with real data or production workflows.

• JavaScript support - github / github_issue
• scriptc run` fails with "ts7 createProgram: project failed to open" on W - github / github_issue
• Static builds fail on Linux/glibc: host clang path is missing `-D_GNU_ - github / github_issue
• v0.0.17 - github / github_release
• v0.0.16 - github / github_release
• v0.0.15 - github / github_release
• v0.0.14 - github / github_release
• v0.0.13 - github / github_release
• v0.0.12 - github / github_release
• v0.0.11 - github / github_release
• v0.0.10 - github / github_release
• v0.0.9 - github / github_release