Skip to content

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

License

Notifications You must be signed in to change notification settings

hyperse-io/ts-node

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

70 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

@hyperse/ts-node

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

build stable version GitHub top language Licence

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

  1. Path Aliases

    • Keep aliases simple and intuitive
    • Use consistent naming patterns
    • Avoid conflicts with built-in module names
  2. Project Structure

  project/
  β”œβ”€β”€ src/          # Source files
  β”œβ”€β”€ dist/         # Compiled files
  β”œβ”€β”€ tsconfig.json # TypeScript configuration
  └── package.json  # Project configuration

Limitations

  1. Requires a valid tsconfig.json file in the project root
  2. Path resolution must be within the rootDir directory
  3. All required properties must be accessible in the tsconfig inheritance chain
  4. Not recommended for production use without thorough testing and validation

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.