@hyperse/ts-node NPM

@hyperse/ts-node

Faster TypeScript/JavaScript transformer without typechecking and node-gyp and postinstall script.

A TypeScript path alias resolver for Node.js applications that works seamlessly with both development (ts-node) and production environments. This package automatically resolves path aliases based on your tsconfig.json configuration, eliminating the need for complex relative imports.

Features

🔄 Automatic path resolution for both source (src) and compiled (dist) directories
🎯 Full TypeScript path alias support via tsconfig.json with extends and module resolution
🚀 ESM-first design with support for Node.js 20.6+
🔧 Zero configuration required - works out of the box
🛠️ Utility functions for dynamic path resolution
✨ Support for TypeScript decorators and metadata reflection
🔍 Smart path alias resolution
🎭 Seamless development and production environments
⚡️ Lightning fast performance with SWC
🧪 Comprehensive test coverage

⚠️ Important Notice

This package is:

Designed primarily for backend applications and unit testing
Currently in experimental status
Requires thorough testing before production use
Runtime sourcemap support via sourceMap: true in tsconfig.json for enhanced debugging

Installation

npm install --save @hyperse/ts-node

Quick Start

1. Configure `tsconfig.json`

{
  "compilerOptions": {
    "rootDir": "./src",
    "outDir": "./dist",
    "baseUrl": "./",
    "sourceMap": true,
    "paths": {
      "@utils/*": ["./src/utils/*"],
      "@components/*": ["./src/components/*"],
      "@config": ["./src/config.ts"]
    }
  }
}

2. Usage in ESM Projects

For Node.js 20.6+:

{
  "scripts": {
    "dev": "node --import=@hyperse/ts-node/register ./src/index.ts",
    "start": "node --import=@hyperse/ts-node/register ./dist/index.js"
  }
}

For Node.js ≤20.5 (deprecated):

{
  "scripts": {
    "dev": "node --loader @hyperse/ts-node/esm ./src/index.ts",
    "start": "node --loader @hyperse/ts-node/esm ./dist/index.js"
  }
}

Environment Variables

Variable	Description	Default
`HPS_TS_NODE_PROJECT`	Path to tsconfig file	`tsconfig.json`
`HPS_TS_NODE_LOG_LEVEL`	Log level 0-4	`2` Info
`HPS_TS_NODE_LOG_TIMESTAMP`	Enable timestamp in logs	`false`

API Reference

`createPathMatcher()`

Create a path resolver for your aliases:

import { createPathMatcher, HpsSpecifierLoader } from '@hyperse/ts-node';
import path from 'path';

const matcher = createPathMatcher('/project/root', {
  '@utils/*': ['src/utils/*'],
  '@components/*': ['src/components/*'],
});

// Resolve paths
const result = matcher('@utils/helper', {
  extensions: ['.ts', '.js'],
  // Optional: custom file existence checker
  fileExists: (filePath) => filePath.includes('index'),
});

Best Practices

Path Aliases
- Keep aliases simple and intuitive
- Use consistent naming patterns
- Avoid conflicts with built-in module names
Project Structure

  project/
  ├── src/          # Source files
  ├── dist/         # Compiled files
  ├── tsconfig.json # TypeScript configuration
  └── package.json  # Project configuration