DOCSEARCHbyAlgolia
Submit Docs

tsx (TypeScript Execute)

repository·master·Indexed 11 days ago

https://github.com/privatenumber/tsx

A developer tool that provides a seamless way to execute TypeScript and ESM files within a Node.js environment without a separate build or compilation step, utilizing esbuild for transformation.

Tokens
28.6K
Snippets
86
Records
190
Agent score
92%

What's inside tsx

  1. Overview of tsx research and policy

    master

    The tsx repository contains engineering research notes, cross-tool synthesis, and implementation maps regarding TypeScript execution. It documents decisions on compatibility boundaries, runtime extensions, and module resolution policies.

    Key areas of research documented include:

    • Module Resolution: Runtime extension and package-subpath policies.
    • Node Integration: Node feature gates and loader integration.
    • CJS Interop: Default-import policies for ambiguous CommonJS __esModule exports.
    • Transform Semantics: Per-file transform semantics and backend verification contracts.

  2. Overview of Oxc transform research

    master
    This repository contains research and documentation regarding Oxc TypeScript transformation, semantic reference analysis, and the behavior of generated helpers. It covers technical details on how Oxc handles various transformation aspects such as import elision, function identity, distribution, and semantic compatibility.

  3. Overview of TypeScript research and behavior

    master
    This research collection explores the behavior of the TypeScript compiler and checker. A fundamental concept to understand is that TypeScript is a type-system resolver; it resolves files to obtain type information and performs static analysis, but it does not function as a JavaScript runtime resolver.

  5. Overview of esbuild research for TypeScript execution

    master
    This research documentation covers how esbuild handles resolution and transformation behaviors specifically relevant to direct TypeScript execution. It is organized into several specialized topics covering module resolution, CJS/ESM interoperability, import analysis, function identity, and CommonJS output.

  6. Enhance Node.js with tsx using the Developer API

    master

    The Developer API allows you to use tsx features without using the tsx CLI command. This is useful when you need more control over the Node.js environment or are integrating with tools that specifically invoke the node binary.

    Note: When using the Developer API, CLI-specific features like Watch mode and the REPL are not available.

  7. Node.js research topics overview

    master

    This repository contains research notes regarding Node.js runtime and loader implementation behaviors. The documentation is organized into specific topics covering module hooks, resolution, interoperability, and native features. Use the following guide to navigate the research areas:

    • Module Hooks: Async module.register() and sync module.registerHooks().
    • Module Resolution: ESM root exports, CommonJS directory mains, and ESM error decoration.
    • Data URL Modules: data: module payload and metadata behavior.
    • Source Maps: Stack formatting and CallSite source-map locations.
    • CommonJS Loader: CommonJS resolution, cache identity, extensions, and ESM error decoration.
    • CJS-ESM Interop: Node's CJS-to-ESM and ESM-to-CJS interoperability.
    • Type Stripping: Node's native TypeScript type-stripping runtime.
    • Feature Boundaries: Smaller Node feature and bug-fix boundaries.

  8. Understand Import Elision behavior

    master

    Import elision refers to how TypeScript removes unused imports or internal aliases during the emit process.

    Key behaviors include:

    • Unused/Type-only Aliases: If a qualified alias (e.g., import Alias = Namespace.Member) is used only as a type or is otherwise unreferenced as a value, TypeScript suppresses the originating module's side effects by eliding the import.
    • Default JavaScript Emit: The compiler removes unreferenced internal aliases and originating import specifiers that have no runtime references. An emptied import is removed entirely rather than being rewritten as a side-effect import.
    • Global Scripts vs. Modules: In Global scripts, top-level qualified value aliases are preserved even if used only as a type. To enable normal elision (removing unused imports), you must make the file an external module (e.g., by adding an export {}).

  9. Configure ES and Engine targets in Oxc

    master

    Oxc supports a wide range of ECMAScript versions from ES2015 through ES2026/ESNext. You can also specify versioned engine targets (e.g., node24.15.0) to ensure compatibility with specific runtime environments.

    If a file path is unknown or contains query parameters, Oxc falls back to default JavaScript module parsing. You can use the following options to override this behavior:

    • lang: Restores TS/TSX language classification.
    • sourceType: Overrides the parser module kind (separately from language classification).

  10. Understand default watch behavior in `tsx`

    master

    By default, tsx watches all imported files. However, it automatically ignores files located in the following directories to optimize performance and avoid unnecessary re-runs:

    • node_modules
    • bower_components
    • vendor
    • dist
    • Hidden directories (any directory starting with .)

    Note: This is distinct from Node.js's built-in --watch flag and is designed to be more robust for dependency tracking.

  11. Understand esbuild's CommonJS output behavior for known exports

    master
    When esbuild generates CommonJS output for Node.js environments where exports are known, it includes a dead-code module.exports annotation. This annotation is specifically designed to be recognized by static CommonJS export lexers, facilitating better interoperability and analysis during the linking process.

  12. Compare tsx with ts-node

    master

    Both tsx and ts-node run TypeScript in Node.js, but they differ in several key areas:

    Featuretsxts-node
    InstallationSingle binary, no peer dependencies. Can be used via npx tsx ./script.ts.Requires typescript or swc as peer dependencies.
    ConfigurationWorks out of the box; no tsconfig.json required.May require initial setup and configuration.
    DefaultsUses sensible defaults based on imports and Node.js version.Relies on TypeScript defaults (may need adjustment).
    Module SupportAutomatically adapts between CJS and ESM; supports require() for ESM.Provides support but may require specific configuration.
    SpeedUses esbuild for fast compilation; does not perform type checking.Uses TypeScript compiler by default (can use swc for speed).
    WatcherIncludes built-in Watch mode.N/A

    For a deeper technical comparison, see the exhaustive comparison repository.