esno

esno is a Node.js runtime enhancement tool that enables seamless execution of TypeScript and ESM modules using esbuild for fast compilation. As of version 0.15+, esno serves as a convenient alias for the tsx package, offering automated CJS/ESM mode detection and caching capabilities.

Package Information

• Package Name: esno
• Package Type: npm
• Language: JavaScript (with TypeScript support)
• Installation: npm install esno or npm install -g esno

Core Imports

esno is primarily used as a CLI tool and does not provide a programmatic API for imports. All functionality is accessed via the command line.

Basic Usage

Direct Execution

Execute TypeScript files directly without pre-compilation:

npx esno hello.ts

Global Installation

Install globally for convenient usage:

npm install -g esno
esno index.ts

As Project Dependency

Add to package.json scripts:

{
  "scripts": {
    "start": "esno index.ts",
    "dev": "esno src/main.ts"
  },
  "dependencies": {
    "esno": "^4.8.0"
  }
}

Then run:

npm run start

Architecture

esno is built as a thin wrapper around the tsx package:

• CLI Wrapper: The main esno executable (esno.js) imports and delegates to tsx/cli
• Zero Configuration: Automatically detects CJS/ESM modes and provides caching
• TypeScript Support: Handles TypeScript files via esbuild for fast compilation
• ESM Native: Built as an ESM module with "type": "module"

Capabilities

CLI Execution

Primary capability for executing TypeScript and JavaScript files with enhanced Node.js runtime.

esno [file] [arguments...]

Parameters:

• file - Path to the TypeScript or JavaScript file to execute
• arguments... - Command line arguments to pass to the executed script

Usage Examples:

# Execute a TypeScript file
esno app.ts

# Execute with arguments
esno script.ts --config production --port 8080

# Execute from current directory
esno ./src/index.ts

# Execute with environment variables
NODE_ENV=production esno server.ts

Supported File Types:

• .ts - TypeScript files
• .tsx - TypeScript JSX files
• .js - JavaScript files (ESM or CommonJS)
• .jsx - JavaScript JSX files
• .mjs - ECMAScript modules
• .cjs - CommonJS modules

Features:

• Fast Compilation: Uses esbuild for rapid TypeScript compilation
• Auto Mode Detection: Automatically detects and handles CJS/ESM module systems
• Caching: Built-in caching for improved performance on subsequent runs
• Zero Config: No configuration files required
• Node.js Compatibility: Full compatibility with Node.js runtime and APIs

Error Handling

esno delegates all execution to tsx, so error handling follows tsx patterns:

• Compilation Errors: TypeScript compilation errors are displayed with file locations
• Runtime Errors: Standard Node.js runtime error handling applies
• File Not Found: Clear error messages when target files don't exist
• Permission Errors: Standard file system permission error handling

Dependencies

esno has minimal dependencies:

{
  "dependencies": {
    "tsx": "^4.19.1"
  }
}

All core functionality is provided by the tsx package, which esno wraps for convenience.